backfill

Localization Backfill

Translate every missing or untranslated key across all i18n locale files using the master locale as the source.

This command orchestrates a set of skills; the skills do not assume any particular i18n tooling. Project-specific paths and commands come from .claude/i18n.config.json.

Bundled scripts

• scripts/find_duplicate_localizations.py — bundled dedupe analyzer used in Step 1 of this skill.
• The translation analysis itself runs through [[analyze]], which bundles its own scripts/check-i18n.py.

When you see ${CLAUDE_PLUGIN_ROOT} below, it refers to this plugin's install root — typically ~/.claude/plugins/cache/efitz-skills/loc/<version>/. If Claude Code does not pre-substitute the variable when you read this file, resolve it yourself: locate the directory containing this SKILL.md, walk up to the plugin root, and use that absolute path. Do NOT fall back to the legacy path ~/Projects/skills/commands/localization-backfill.scripts/.

Configuration

Same config used by the i18n skill family — see [[analyze]] for the full schema. Required fields:

• locales_dir
• master_locale
• file_extension

Optional:

{
  "format_command":    "<shell command that normalizes formatting, e.g. 'pnpm run format'>",
  "dedupe_plan_file":  "<path where the dedupe script writes its plan, default 'localization_dedup_plan.txt'>"
}

If format_command is absent, the format step is skipped.

Process

Step 1: Deduplicate

Run the bundled dedupe script (${CLAUDE_PLUGIN_ROOT} is the root directory of this plugin):

uv run "${CLAUDE_PLUGIN_ROOT}/scripts/find_duplicate_localizations.py" \
  --skippolicy --reference

The script reads .claude/i18n.config.json to find the master locale, then writes its plan to localization_dedup_plan.txt in the current directory (override with -o).

Then:

1. Read the plan file.
2. If it contains REFER recommendations:
   1. Back up locale files: mkdir -p /tmp/i18n-dedup-backups && cp <locales_dir>/*.<ext> /tmp/i18n-dedup-backups/.
   2. Apply each REFER change to the master locale — replace the literal value with a {{reference}} template.
   3. Apply the same reference change to every non-master locale (jq filter).
   4. Run format_command from config if present.
   5. Re-run the dedupe script to verify zero duplicates remain.
3. If no duplicates, continue to step 2.