I18n Extract

Locale File Locations

Main app:

• Path: src/entrypoints/_locales/{locale}.ts
• Namespace: "common"

Plugins:

• Path: src/plugins/{plugin-path}/_locales/{locale}.ts
• Namespace: read the exported namespace constant from src/plugins/{plugin-path}/_locales/index.ts

en-US Locale File Format

import type { LanguageMessages } from "@complexity/i18n";

export default {
  keyName: "Simple string",
  nested: {
    key: "Nested value",
    withParam: "Hello {name}",
    withComponent: "Click <0>here</0> to continue",
  },
} as const satisfies LanguageMessages;

Non-English locale files are a separate follow-up step and typically mirror the same shape using the local Translations type from _locales/index.ts.

File Inspection Order

Inspect files in this order. Do not guess before checking.

1. Target source file(s)
2. Closest target locale namespace file: _locales/index.ts
3. Target en-US.ts
4. Neighboring source usage of existing keys in the same feature
5. Only then decide reuse vs new key, and formatter choice

Extraction Rules

1. DO NOT import t or Trans - globally available (auto-imported)
2. Extract to en-US first - English is source of truth
3. Use the real namespace - never infer plugin namespace from folder name; always read _locales/index.ts
4. Use full key path - format: namespace.section.key
5. Reuse existing keys when semantics match - search nearby locale sections before adding a new key
6. Prefer nested semantic keys - base keys on UI role, not raw English text
7. Use t(...) for plain text
8. Only use Trans when the translated string contains component placeholders like <0>...</0>
9. Preserve placeholders exactly - convert runtime values into {name} / {count:number} / {date} style placeholders
10. Do not extract non-visible DOM attributes - skip HTML aria-label, alt, and DOM title attributes
11. Do extract visible component props - props like title, label, description, placeholder, message, content may be visible UI text depending on the component
12. Do not update non-English locale files during extraction unless the user explicitly asks for that follow-up work

Key Naming Rules

• Prefer the existing subtree in the target locale file if one already matches the feature.
• Use stable semantic names such as dialog.confirm.title, filters.sort.newest, buttons.save.
• Do not create keys directly from the literal English text.
• Do not create flat one-off keys when a nested group already exists.
• Reuse an existing key only when the meaning matches, not just the raw text.

What To Extract

Extract visible user-facing strings from:

• JSX text nodes
• string literals rendered in components
• visible component props such as label, description, placeholder, message, content, text
• menu items, dialog content, toast titles/descriptions, button labels, filter labels, section headings
• strings inside arrays or objects when they are rendered to users

What To Skip

Skip:

• HTML aria-label, alt, and DOM title attributes
• internal identifiers, enum values, test text, analytics/event names, CSS class names
• URLs, file paths, selectors, storage keys, query parameter names
• strings already passed to t(...) or Trans

Formatter Selection Rules

Choose the smallest correct mechanism:

Use plain strings for

• static copy
• simple runtime variables like {name}
• number/date/list formatting such as {count:number}, {date:date}, {items:list}

Use dt(...) for

• plural variations
• enum variations
• only when locale-specific grammar actually depends on the variable

Do not use dt(...) for

• plain {name} interpolation
• {count:number} / {date:date} / {items:list} formatting
• JSX/component placeholders handled by Trans

Transformation Rules

Plain strings

<Button>Save</Button>

Becomes something like:

<Button>{t("common.buttons.save")}</Button>

Interpolated values

`Expires ${date}`

Becomes locale text like: