audit-i18n — Natural, Human-Sounding Translations

Degree of freedom: MIXED — Quality judgment and rewrite [HIGH freedom]; Phase 2 key-diff and Phase 4 locale walk [LOW freedom — run exactly].

Audit-and-fix exception. Find bad copy, then fix it. Not present-then-stop.

>

Fix the strings the audit named — extract, rewrite, add the missing key — with surgical edits to the source line and the locale entry; do not reformat or re-key whole translation files, and copy you did not audit stays as it is. Unrelated bugs met on the way go in the report as follow-ups. Add tests only where the repo already tests i18n; the Phase 2 key-diff scripts stay out of the commit.

Translations that read like machine output erode user trust — especially in the user's own language. Find every unnatural, jargon-heavy, or technically worded string and rewrite it to sound like a real person in that locale.

The goal: every string should sound like it was written by a native speaker who understands the user, not translated from English by a developer.

This skill vs neighbors

Core principles for good copy

These apply to every string in every locale:

How to reason — Observe → Interpret → Classify → Severity

1. Observe — quote the source string or locale key (file:line) and the base-locale counterpart
2. Interpret — does a native speaker get a next step, or a literal/dev-voiced phrase?
3. Classify — hardcoded / missing key / too-literal / wrong-tone / format-mismatch / untranslated-key
4. Severity — checkout, auth, and error strings first; [TODO] if you are not a native speaker

Worked example

Observe: CheckoutButton.tsx:42 renders <button>Submit</button> (no i18n key). ja errors.email_invalid is "無効なメールアドレス"; en key exists. Interpret: the CTA does not name the outcome; JA is a literal of "Invalid email address" — it blames and gives no next step. Classify: hardcoded + too-literal error. Severity: High — primary checkout CTA and a blocking validation error. Finding: extract buttons.place_order; rewrite JA to guide a typo check; then apply (audit-and-fix).

Phase 0: Detect the i18n setup [HIGH freedom]

package.json   → i18next, react-i18next, next-intl, vue-i18n, @angular/localize,
                 i18n-js, rosetta, lingui, typesafe-i18n
src/i18n/      → translation files
locales/       → JSON/YAML translation files
messages/      → next-intl message files
public/locales → common path for react-i18next

Identify:

• Library: react-i18next / next-intl / vue-i18n / lingui / custom
• Active locales: list of language codes (en, ja, fr, de, zh, etc.)
• Translation file format: JSON / YAML / TypeScript / PO files
• Completeness: are all locales present? Do non-English files have all keys?

Fetch library docs:

context7:resolve-library-id
{
  "libraryName": "react-i18next"
}

Phase 1: Find hardcoded strings in source code [HIGH freedom]

Look for user-facing text that bypasses the i18n system entirely.

Scan for:

• String literals in JSX/TSX: <p>Welcome back</p>, <button>Save</button>
• Template literals with user-visible content: ` Hello ${name} `
• Alert/toast calls with hardcoded strings: toast.error("Something failed")
• Error message strings in API handlers returned to the client
• Placeholder text: placeholder="Enter your email"
• Aria labels: aria-label="Close dialog"
• alt text on meaningful images

Use shell to scan (the codebase search tools may be slow on large repos):

grep -rn 'placeholder="' src/ --include="*.tsx" --include="*.jsx" | head -30
grep -rn '"en":' src/ --include="*.ts" --include="*.tsx" | head -20

Build a list: file path, line number, string content, whether it has an i18n key already.

Phase 2: Audit translation file completeness [LOW freedom — run exactly]

For each locale, check that all keys from the base locale (usually en) exist:

# Example: compare en.json vs ja.json key counts
node -e "
const en = require('./public/locales/en/common.json');
const ja = require('./public/locales/ja/common.json');
const missing = Object.keys(en).filter(k => !ja[k]);
console.log('Missing in ja:', missing);
"

Or for next-intl format:

node -e "
const en = require('./messages/en.json');
const ja = require('./messages/ja.json');
function findMissing(base, target, path='') {
  for (const k of Object.keys(base)) {
    const kp = path ? path+'.'+k : k;
    if (!(k in target)) console.log('MISSING:', kp);
    else if (typeof base[k] === 'object') findMissing(base[k], target[k], kp);
  }
}
findMissing(en, ja);
"

Phase 3: Review translation quality [HIGH freedom]

This is the most important phase. For each locale, review every string against the natural-language principles at the top of this skill.

What to look for in each category

Error messages — must guide, not blame, and tell the user what to do:

// Before
"errors.email_invalid": "Invalid email address"

// After
"errors.email_invalid": "That doesn't look like a valid email — check for typos and try again"

Action buttons — must describe the outcome, not just label the input:

// Before
"buttons.submit": "Submit"
"buttons.confirm": "OK"

// After
"buttons.submit": "Save changes"  // or whatever the action actually does
"buttons.confirm": "Got it"       // or the specific action: "Delete account", "Send message"

Empty states — should explain and invite, not just state the absence:

// Before
"empty.projects": "No projects"

// After
"empty.projects": "You haven't created any projects yet. Start one to get going."

Success messages — should feel warm and confirm the action clearly:

// Before
"success.saved": "Data saved successfully"

// After
"success.saved": "Saved!"  // or "Your changes are saved"

Loading states — should be human:

// Before
"loading.data": "Loading data..."

// After
"loading.data": "Getting things ready…"  // or just omit "Loading" entirely

Locale-specific tone guidelines

Phase 4: Walk the live app in each locale (Playwright) [LOW freedom — run exactly]

For each active locale:

1. Navigate to the locale-specific URL or trigger the locale switcher
2. Walk the key flows: onboarding, core feature, error states, empty states, settings
3. Screenshot each screen for visual review

PW="npx --yes @playwright/cli@latest"
$PW -s=i18n open --headed "http://localhost:3000/ja"   # or set the locale cookie, then `goto`
$PW -s=i18n snapshot                                    # capture the state
$PW -s=i18n screenshot --filename ".playwright-mcp/i18n-ja-<route>.png"

Look for:

• Strings that are still in English (untranslated keys showing as key names like common.save)
• Text that overflows its container in longer languages (German, Finnish, Russian)
• Date/time formatting that doesn't match the locale (30/01/2026 vs Jan 30, 2026 vs 2026年1月30日)
• Currency symbols in the wrong position ($10.00 vs 10,00 € vs ¥1,000)
• Numbers using the wrong decimal/thousands separator (1,234.56 vs 1.234,56)
• Plural forms: English has singular/plural; many languages have more forms

Save screenshots under .playwright-mcp/.

Self-critique before applying [LOW freedom — do not skip]

1. Evidenced — file:line + key, not "Japanese feels off"
2. Native-or-TODO — if you are not a native speaker, mark [TODO]; do not ship confident wrong idiom
3. Completeness first — missing keys listed before quality nits
4. Right owner — breakpoint overflow that is not locale-length → audit-responsive; WCAG → audit-accessibility
5. Do not delete copy to "fix" i18n — extract or rewrite

Phase 5: Fix — priority order [HIGH freedom]

Fix 1: Extract all hardcoded strings

For every hardcoded string found in Phase 1, create an i18n key and replace it:

// Before (react-i18next)
<p>Welcome back, {name}!</p>

// After
const { t } = useTranslation('common');
<p>{t('welcome_back', { name })}</p>

// en/common.json
"welcome_back": "Welcome back, {{name}}!"

// ja/common.json
"welcome_back": "おかえりなさい、{{name}}さん！"

Fix 2: Rewrite poor translations

Edit the translation files directly. Prioritise:

1. Error messages that blame or confuse users
2. Empty states that dead-end users
3. Action buttons that say "Submit" or "OK"
4. Any string a native speaker would read and say "that's not how we talk"

Fix 3: Add missing locale keys

For any key missing in a non-English locale, add a natural translation. If you don't have a native speaker for a locale, use a clearly-marked placeholder:

"some_key": "[TODO: needs native Japanese review] {{count}} items selected"

Fix 4: Fix number/date/currency formatting

Use the i18n library's format functions rather than manual formatting:

// react-i18next with i18next-icu or i18next-intervalPlural
t('items_count', { count: 5 }) // handles plural forms automatically

// Intl API for dates and numbers (framework-agnostic)
new Intl.DateTimeFormat(locale, { dateStyle: 'long' }).format(date);
new Intl.NumberFormat(locale, { style: 'currency', currency: 'JPY' }).format(1234);

Phase 6: i18n audit report

## i18n Audit Report — [App] — [Date]

### Active locales
[list with coverage % — keys present / total keys]

### Hardcoded strings found
| File | Line | String | Action |
|------|------|--------|--------|
| src/components/Foo.tsx | 42 | "Save" | Extracted to key `buttons.save` |

### Translation quality issues fixed
| Locale | Key | Before | After | Issue type |
|--------|-----|--------|-------|-----------|
| ja | errors.email_invalid | "無効なメールアドレス" | "メールアドレスが正しくないようです。入力内容をご確認ください。" | Too literal, not helpful |

### Missing keys added
[count per locale]

### Formatting fixes
[date/number/currency issues found and fixed]

### Still needs native review
[keys marked [TODO] that need a human native speaker]