nextjs-json-i18n-ai-translate

Next.js JSON i18n: Translate and Fill

When to use

Use this Skill when:

• The project is Next.js
• i18n resources are .json files (for example en.json, de.json)
• The user wants to add locales, fill missing translations, or align structure (and optionally remove extra keys)

Not a fit when:

• The dictionary format is not JSON (for example .ts, .yaml, .po)
• The user is translating long-form content (docs/pages) or code comments (use the general translation flow, not the i18n subcommand)

Confirm user intent first

Before running anything, ask and confirm:

1. Scope: which i18n directory to process (there may be multiple)
2. Source locale: default is en (do they need another, for example zh-CN)
3. Target locales: which locale codes (for example ru,de,fr)
4. Mode:
   • fill: only fill missing values (recommended default)
   • overwrite: re-translate everything (only if explicitly requested)
   • prune: align structure and remove extra keys from targets (only if explicitly requested)
5. Preview first: default to --dry for stats, then run the real write after confirmation

Quick workflow

1) Locate the i18n directory

From the project root, search for en.json first.

• Common locations: src/i18n, src/messages, messages, locales, public/locales
• If multiple candidates exist, list them and ask the user to pick which directory (or directories) to process

2) Run a dry preview first

After confirming baseDir, targets, and mode:

npx @thor123141245r/ai-translate i18n --base <baseDir> --source en --targets ru,de --dry

3) Execute the real translation

Only after the user confirms the dry-run stats:

npx @thor123141245r/ai-translate i18n --base <baseDir> --source en --targets ru,de --mode fill

Target locale inference

If the directory already contains some target *.json files and the user does not pass --targets, the CLI can infer target locales from existing files. If the directory contains only the source file (for example only en.json), you must provide --targets explicitly.

Non-standard source filename

If the source file is not named like en.json (for example en-US.json), use --file:

npx @thor123141245r/ai-translate i18n --base <baseDir> --source en --file en-US.json --targets ru --dry

Provider configuration and API keys

This tool requires a working model provider configuration; otherwise translation will fail.

• Prefer environment variables for API keys; do not commit keys into the repo
• You can write provider config into .ai-translate.json via ai-translate set provider ...

Example:

export OPENAI_API_KEY="YOUR_KEY"
npx @thor123141245r/ai-translate set provider openai

Output and cache

• By default, a cache file .ai-translate.cache.json is written under baseDir to reduce repeated translations
• Target locale files are written as <lang>.json (for example ru.json)

Post-run checks

After completion:

1. Run Next.js dev/build to ensure JSON files parse correctly
2. Spot-check strings with placeholders to ensure placeholders are preserved (for example {{name}}, {name}, %s)