Claude md for Internationalization i18n Setup

Internationalization (i18n) remains one of the most tedious aspects of web development. Managing translation keys, coordinating locale files across teams, and keeping translations in sync with codebase changes consumes hours of manual work. Claude Code combined with well-crafted skills transforms this workflow entirely.

This guide shows you how to set up Claude for internationalization, automate repetitive translation tasks, and build a reproducible i18n pipeline that scales with your project.

Understanding the i18n Challenge

Most projects hit the same pain points when scaling internationalization:

Translation keys scattered across multiple files and formats (JSON, YAML, PO, XLIFF)
Stale translations that no longer match the source strings
Manual coordination between developers and translators
No automated way to detect missing or unused keys

Claude Code addresses these issues through skills that understand your project’s translation structure and can act as an intelligent intermediary between your codebase and translation workflow.

Setting Up Your i18n Skill

Create a dedicated skill for internationalization tasks. This skill will understand your project’s locale structure and provide commands for common i18n operations.

---
name: i18n
description: "Internationalization helper for managing translations, extracting keys, and validating locale files"
---

# Internationalization Helper

This skill assists with translation management across your project.

## Available Commands

- `extract`: Find all translation keys used in your codebase
- `validate`: Check locale files for missing or duplicate keys
- `sync`: Compare source locale against target locales
- `missing`: List all untranslated strings for a given locale

## Configuration

Set these environment variables or provide them when prompted:
- `SOURCE_LOCALE`: Primary language (default: en)
- `LOCALE_DIR`: Path to translation files (default: ./locales)
- `TRANSLATION_FORMAT`: json, yaml, or po

Save this as skills/i18n.md in your project. The skill declares its dependencies upfront—Read, Write, Bash, and Glob give it the file system access needed to analyze and modify translation files.

Extracting Translation Keys Automatically

One of the most valuable automation tasks is finding all translation keys actually used in your codebase. Instead of manually hunting through components, create a helper function within your i18n skill that scans your source files.

// Extract all i18n keys from source files
function extractKeys(sourceDir, patterns) {
  const keys = new Set();
  
  for (const file of glob.sync(`${sourceDir}/**/*.{js,jsx,ts,tsx,vue,svelte}`)) {
    const content = read_file(file);
    
    // Match common i18n patterns
    const i18nPatterns = [
      /t\(['"`]([^'"`]+)['"`]\)/g,  // t('key')
      /i18n\.t\(['"`]([^'"`]+)['"`]\)/g,  // i18n.t('key')
      /\$t\(['"`]([^'"`]+)['"`]\)/g,  // $t('key') (Vue)
    ];
    
    for (const pattern of i18nPatterns) {
      let match;
      while ((match = pattern.exec(content)) !== null) {
        keys.add(match[1]);
      }
    }
  }
  
  return Array.from(keys).sort();
}

Run this extraction periodically—before each release, after feature branches merge, or as part of your CI pipeline. The output gives you a complete picture of which translation keys your application actually uses.

Validating Locale Files

Translation drift happens when developers add English strings but forget to add corresponding translations. A validation step catches these gaps before they reach production.

// Validate all locale files against source
function validateLocales(sourceLocale, targetLocales) {
  const sourceKeys = loadKeys(sourceLocale);
  const issues = [];
  
  for (const locale of targetLocales) {
    const targetKeys = loadKeys(locale);
    
    // Find missing translations
    const missing = sourceKeys.filter(k => !targetKeys.includes(k));
    if (missing.length > 0) {
      issues.push({
        locale,
        type: 'missing',
        keys: missing
      });
    }
    
    // Find orphaned keys (in translation but not in source)
    const orphaned = targetKeys.filter(k => !sourceKeys.includes(k));
    if (orphaned.length > 0) {
      issues.push({
        locale,
        type: 'orphaned',
        keys: orphaned
      });
    }
  }
  
  return issues;
}

Integrate this validation into your pre-commit hooks using a skill like frontend-design to ensure no translation gaps slip through code review.

Integrating with Translation Workflows

For teams working with external translators or translation management systems (TMS), Claude can act as a bridge. The pdf skill becomes valuable here—you can generate translation briefs as PDF documents to send to translators, then import their responses back into your locale files.

# Example: Generate a translation request document
claude -p "Create a PDF containing all missing translation keys for French locale. 
Include the English source strings and a notes column for translators.
Save as translation-request-fr.md"

This approach works well with tools like Localize, Transifex, or Crowdin. Claude can parse exported translation files from these services and merge them into your project structure.

Managing Locale Files Across Teams

When multiple developers work on translations, conflicts become inevitable. A few strategies keep things manageable:

Central translation dictionary: Store translations in a dedicated package or monorepo shared across projects
Namespace by feature: Organize keys by feature area (auth.login.title, dashboard.stats.label) rather than flat structure
自动化 CI checks: Reject PRs that add new translation keys without providing translations for all active locales

The tdd skill pairs well here—write tests that verify translation completeness as part of your test suite:

// Test that all required locales have complete translations
test('all locales have complete translations', () => {
  const en = require('./locales/en.json');
  const fr = require('./locales/fr.json');
  const de = require('./locales/de.json');
  
  const enKeys = flattenObject(en);
  
  expect(Object.keys(fr)).toHaveSameKeysAs(Object.keys(en));
  expect(Object.keys(de)).toHaveSameKeysAs(Object.keys(en));
});

Practical Example: React i18n Setup

For React projects using react-i18next, Claude can scaffold your entire i18n infrastructure:

claude -p "Set up internationalization for this React project using react-i18next.
Create the i18n configuration, locale files for English and Spanish, 
and wrap the app with the I18nextProvider. Include a hook for accessing translations."

The skill responds with complete, production-ready code tailored to your project structure. This eliminates the boilerplate that makes i18n setup feel overwhelming.

Scaling Your i18n Workflow

As your project grows, consider these advanced patterns:

Pluralization rules: Different languages handle plurals differently—ensure your i18n library handles Arabic’s six plural forms or Chinese’s lack of plurals
Gender and context: Some translations vary by speaker gender or context—build this into your key structure (user.gender.male, user.gender.female)
RTL support: For right-to-left languages, verify your layouts adapt properly—combine with canvas-design to preview RTL layouts

Next Steps

Start with a minimal i18n skill and expand it as your needs grow. The key is automation—every task you perform manually on translations is a candidate for skill-ification.

Explore related skills that complement internationalization: frontend-design for UI localization, pdf for translation documentation, and supermemory to remember translation context across sessions.

Built by theluckystrike — More at zovo.one