Skip to main content

Localization — Add Local English Keys When Needed

Allow local en.json additions for new translation keys; use t() with matching keys and placeholders

Source: .agents/rules/no-direct-locale-additions.mdc

Metadata​

  • alwaysApply: true

Content​

Localization — Add Local English Keys When Needed

When adding new user-facing copy, wire the code with t() and add the matching English entry to public/locales/en.json when the key is missing locally.

public/locales/en.json is gitignored and is used by the pre-push translation sync workflow. Keep edits focused to the keys needed for the current change.

What to do​

  • Use t('key') or t('key', { param: value }) in code with matching key and placeholder names (e.g. {{name}}, {{count}}).
  • Leave the key as a literal: e.g. t('hi-name', { name: greetingName }).
  • Add the matching English source string to public/locales/en.json when it is missing.
  • For placeholders, keep the locale value placeholders aligned with the code params, e.g. "hi-name": "Hi, {{name}}".

Rules​

  1. Add or update only the specific public/locales/en.json entries required by the current change.
  2. Do not bulk-edit, reorder, or reformat locale files.
  3. Do not edit non-English locale files unless explicitly requested.
  4. Do not edit generated CSV locale files unless the task is specifically about the translation export workflow.
  5. Use t('key') or t('key', { placeholderName: value }) with placeholder names that exactly match the locale value.