glot fix

Auto-insert glot-message-keys comments for dynamic translation keys

The fix command automatically inserts glot-message-keys comments for dynamic translation keys that cannot be statically analyzed. This declares expected keys so that glot can track them properly.

Usage

npm

npx glot fix [OPTIONS]

Options

--apply · boolean · default: "false"

Actually insert comments. Without this flag, glot runs in dry-run mode and only shows what would be changed.

--source-root · string

Override the source code root directory. Defaults to the value from configuration file.

--messages-root · string

Override the messages directory path. Defaults to the value from configuration file.

--primary-locale · string

Override the primary locale. Defaults to the value from configuration file.

-v, --verbose · boolean · default: "false"

Enable verbose output for debugging.

Why Use Fix?

When you use dynamic translation keys like t(`${prefix}.label`), glot cannot determine which keys are used at build time. This causes two problems:

1. Dynamic key warnings - The check command reports these as warnings
2. Clean refuses to run - The clean command won’t run to prevent accidental key deletion

The solution is to add glot-message-keys comments that declare which keys are expected. The fix command automates this by:

1. Analyzing your template literal keys
2. Inferring appropriate glob patterns
3. Inserting the correct comment syntax (JSX, HTML, or JS depending on context)

What Gets Fixed

Template literals with expressions

Keys using template literals with dynamic parts:

t(`${prefix}.submit`)        // Fixed: pattern "Namespace.*.submit"
t(`error.${code}`)           // Fixed: pattern "Namespace.error.*"
t(`items.${type}.label`)     // Fixed: pattern "Namespace.items.*.label"

What cannot be fixed

Pure variable keys cannot have patterns inferred:

t(keyName)                   // Cannot fix - no pattern can be inferred
t(getKey())                  // Cannot fix - runtime value

For these, you must manually add glot-message-keys comments.

Dry-Run Mode (Default)

Preview what comments would be inserted:

npm

npx glot fix

Output:

  --> ./src/components/Button.tsx:6:21
     |
   6 |     return <button>{t(`${prefix}.submit`)}</button>;
     |                     ^
   +     {/* glot-message-keys "Common.*.submit" */}

Would insert 1 comment(s) in 1 file(s).
Run with --apply to insert these comments.

If there are unfixable variable keys, they are reported separately:

Cannot fix 1 dynamic key(s) (variable keys without pattern hints):

  --> ./src/components/Dynamic.tsx:5:19
     |
   5 |     return <span>{t(keyName)}</span>;
     |                   ^
   = reason: variable key

Apply Changes

Insert the declaration comments:

npm

npx glot fix --apply

Output:

  --> ./src/components/Button.tsx:6:21
     |
   6 |     return <button>{t(`${prefix}.submit`)}</button>;
     |                     ^
   +     {/* glot-message-keys "Common.*.submit" */}

Inserted 1 comment(s) in 1 file(s).

Result

Before:

const t = useTranslations("Common");

export function Button({ prefix }: { prefix: string }) {
  return <button>{t(`${prefix}.submit`)}</button>;
}

After:

const t = useTranslations("Common");

export function Button({ prefix }: { prefix: string }) {
  {/* glot-message-keys "Common.*.submit" */}
  return <button>{t(`${prefix}.submit`)}</button>;
}

JSX vs Non-JSX Context

Glot automatically detects the context and uses the appropriate comment syntax:

JSX context (inside JSX children):

<div>
  {/* glot-message-keys "Common.*.label" */}
  <span>{t(`${type}.label`)}</span>
</div>

Non-JSX context (regular JavaScript):

function getLabel(type: string) {
  // glot-message-keys "Common.*.label"
  return t(`${type}.label`);
}

Astro template context:

<div>
  <!-- glot-message-keys "Common.*.label" -->
  {t(`${type}.label`)}
</div>

Pattern Inference

Glot infers patterns based on the template literal structure:

Template	Inferred Pattern
`${var}.key`	Namespace.*.key
`prefix.${var}`	Namespace.prefix.*
`${a}.${b}.suffix`	Cannot infer (multiple expressions)

Templates with multiple dynamic expressions cannot be automatically fixed because the pattern would be too broad. Add glot-message-keys manually for these cases.

Workflow

1. Run Fix (Dry-Run)

   Preview what comments would be inserted:

   npm

   npx glot fix
   
2. Review Changes

   Check that the inferred patterns make sense for your use case.

3. Apply Changes

   Insert the comments:

   npm

   npx glot fix --apply
   
4. Handle Unfixable Keys

   For any reported variable keys that couldn’t be fixed, manually add glot-message-keys comments:

   // glot-message-keys "Namespace.key1", "Namespace.key2"
   return <span>{t(dynamicKey)}</span>;
   
5. Commit Changes

   Commit the changes to your repository:

   git add -A
   git commit -m "chore: add glot-message-keys for dynamic translation keys"
   

Related

Directives

Learn about glot-message-keys syntax and patterns

Missing Keys

Understanding dynamic key detection

Check Command

Run i18n checks

Clean Command

Remove unused translation keys