Software Localization Skill

Workflow Overview

1. Detect Project Type - Identify the localization framework and file format
2. Validate Target Language - Ensure a valid ISO 639 language code is provided
3. Extract Source Strings - Load English (en/en-us/en_us) as the base
4. Dual Translation - Two independent translator sub-agents produce translations
5. Verification - A third sub-agent compares results and selects the best translations
6. Output - Generate the localization file in the correct format

Step 1: Detect Project Type

Common Patterns to Check

public/locales/

src/locales/

{"key": "value"}

src/translations/

lang/

{"key": {"defaultMessage": "..."}}

src/locales/

locales/

{"key": "value"}

src/assets/i18n/

src/locale/

*.lproj/Localizable.strings

"key" = "value";

res/values-*/strings.xml

<string name="key">value</string>

config/locales/

en:\n  key: value

locale/*/LC_MESSAGES/

msgid "key"\nmsgstr "value"

Resources/

*.resx

<data name="key"><value>...</value></data>

lib/l10n/

assets/translations/

{"key": "value", "@key": {...}}

locales/

translations/

resources/lang/

return ['key' => 'value'];

messages/

locales/

{"namespace": {"key": "value"}}

*.po

*.pot

msgid/msgstr

Detection Commands

# Find common localization directories
find . -type d \( -name "locales" -o -name "locale" -o -name "i18n" -o -name "l10n" -o -name "translations" -o -name "lang" -o -name "*.lproj" -o -name "values-*" \) 2>/dev/null | head -20

# Find localization files
find . -type f \( -name "*.json" -o -name "*.yaml" -o -name "*.yml" -o -name "*.strings" -o -name "*.xml" -o -name "*.po" -o -name "*.pot" -o -name "*.resx" -o -name "*.arb" -o -name "*.xliff" \) 2>/dev/null | grep -E "(locale|i18n|l10n|lang|translation|messages|values)" | head -30

Important: Examine the English Source

• en.json

  ,

  en-US.json

  ,

  en_US.json

• en.yaml

  ,

  en-US.yaml

• en.lproj/Localizable.strings

• values/strings.xml

  (Android default)

• en.po

  ,

  messages.pot

Step 2: Validate Target Language

Required Information

Clarification Required For

• "Chinese" → Ask: Traditional (zh-TW, zh-HK), Simplified (zh-CN, zh-Hans), or another variant?
• "Spanish" → Ask: Spain (es-ES), Latin America (es-419), Mexico (es-MX), or general (es)?
• "Portuguese" → Ask: Brazil (pt-BR) or Portugal (pt-PT)?
• "Serbian" → Ask: Cyrillic (sr-Cyrl) or Latin (sr-Latn)?
• "Norwegian" → Ask: Bokmål (nb) or Nynorsk (nn)?
• "Malay" → Ask: Malaysia (ms-MY), Singapore (ms-SG), or Brunei (ms-BN)?

Common ISO 639-1/BCP 47 Codes

Code Format

• If project uses

  en-US

  → use

  fr-FR

  ,

  de-DE

  , etc.
• If project uses

  en_US

  → use

  fr_FR

  ,

  de_DE

  , etc.
• If project uses

  en

  → use

  fr

  ,

  de

  , etc.

Step 3: Extract Source Strings

• Preserve keys exactly - Do not modify key names
• Note placeholders -

  {name}

  ,

  {{count}}

  ,

  %s

  ,

  %d

  ,

  %@

  , etc.
• Note HTML/markup -

  <b>

  ,

  <a href="...">

  , etc.
• Note pluralization -

  one

  ,

  other

  ,

  few

  ,

  many

  forms
• Note context - ICU message format, gender variations, etc.

Step 4: Dual Translation with Sub-Agents

translator-alpha

translator-beta

Instructions for Translators

1. You are a master linguist fluent in both English and {TARGET_LANGUAGE}
2. Translate each string maintaining natural, idiomatic expression
3. CRITICAL: Preserve all formatting exactly:
   • Placeholders:

     {variable}

     ,

     {{variable}}

     ,

     %s

     ,

     %d

     ,

     %1$s

     ,

     %@

   • HTML tags:

     <b>

     ,

     <i>

     ,

     <a href="...">

     ,

     <br/>

   • Special characters:

     \n

     ,

     \t

     ,

     \"

     ,

     \'

   • Whitespace at start/end of strings
   • Markdown formatting if present
4. Adapt idioms appropriately - don't translate literally if unnatural
5. Consider formality level (formal/informal "you" where applicable)
6. Provide a confidence score (0.0-1.0) for each translation:
   • 1.0: Certain, standard translation
   • 0.8-0.9: High confidence, minor ambiguity
   • 0.6-0.7: Moderate confidence, context-dependent
   • Below 0.6: Low confidence, needs review

Output Format from Translators

{
  "translations": [
    {
      "key": "original.key",
      "source": "English text",
      "translation": "Translated text",
      "confidence": 0.95,
      "notes": "Optional notes about translation choices"
    }
  ]
}

Step 5: Verification with Adjudicator Sub-Agent

translator-adjudicator

• Original English strings
• Translation A (from translator-alpha) with confidence scores
• Translation B (from translator-beta) with confidence scores

Adjudicator Instructions

1. Accuracy - Does it convey the same meaning?
2. Idiomaticity - Does it sound natural in the target language?
3. Formatting preservation - Are all placeholders/tags intact?
4. Consistency - Does terminology match across strings?
5. Confidence scores - Factor in translator certainty

{
  "key": "original.key",
  "selected": "A" | "B" | "merged",
  "final_translation": "The selected or merged translation",
  "reason": "Brief explanation of choice"
}

Step 6: Generate Output File

JSON Format

{
  "key1": "translation1",
  "key2": "translation2"
}

YAML Format

target_locale:
  key1: translation1
  key2: translation2

iOS Strings Format

/* Comment */
"key1" = "translation1";
"key2" = "translation2";

Android XML Format

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="key1">translation1</string>
    <string name="key2">translation2</string>
</resources>

PO Format

msgid "source text"
msgstr "translation"

Error Handling

• Missing source file: Ask user to specify the English source location
• Ambiguous language: Always ask for clarification (see Step 2)
• Unknown format: Ask user about the localization framework
• Large files: Process in batches if over 200 strings

Quality Checklist

• All keys from source are present in output
• No extra keys were added
• All placeholders are preserved exactly
• File encoding matches source (usually UTF-8)
• File format matches project conventions
• Pluralization rules are correct for target language