FlClash/.claude/commands/i18n.md

Scan lib/ for hardcoded Chinese strings and internationalize them following the project's ARB conventions.

Instructions

You are performing i18n extraction for a Flutter project that uses the Flutter Intl plugin with ARB files.

Project localization context

• ARB files: arb/intl_en.arb, arb/intl_zh_CN.arb, arb/intl_ja.arb, arb/intl_ru.arb
• Key conventions: camelCase, flat keys (no nesting, no @ metadata), semantic naming
  • Short labels: rule, global, direct, edit, confirm
  • Descriptive suffix Desc: themeDesc, tunDesc, logsDesc
  • Validation suffix: profileNameNullValidationDesc
• Generated code: lib/l10n/l10n.dart (DO NOT edit generated files)
• Access patterns:
  • In widgets with BuildContext: context.appLocalizations.key (import common.dart)
  • In controllers/providers/non-widget code: currentAppLocalizations.key (import app_localizations.dart)

Step 1: Find hardcoded Chinese strings

Use Grep to search lib/ for Chinese characters. The regex pattern for Chinese characters is [\x{4e00}-\x{9fff}].

Important filters:

• Exclude lib/l10n/ (generated localization files)
• Exclude lines that already use appLocalizations or currentAppLocalizations
• Exclude false positives that are NOT Chinese text:
  • Arrow symbols: ↑ ↓ ← → (Unicode arrows, not CJK)
  • Middle dot: · (U+00B7, not CJK)
  • Command symbol: ⌘ (U+2318, not CJK)
  • Other CJK punctuation that is used as UI symbols, not translatable text

For each match, read the surrounding context (5-10 lines) to understand:

• What the string represents (label, error message, tooltip, dialog text, etc.)
• Whether it's inside a widget (has BuildContext available) or non-widget code
• Whether it appears in a Text(), TextSpan(), title:, label:, or other text position

Step 2: Generate ARB keys

For each hardcoded Chinese string:

1. Choose a key name following project conventions:

   • Use the Chinese meaning to derive an English camelCase key
   • Keep it concise: createConfig not createAConfigurationForTheProfile
   • Use Desc suffix for descriptive/explanatory text
   • Use existing similar keys as reference (check arb/intl_en.arb for patterns)

2. Determine the English translation (the value for intl_en.arb)

3. Determine the Chinese translation (the value for intl_zh_CN.arb) — this is the original hardcoded string

4. For ja and ru: use the English translation as a placeholder (translators will fill these in later)

Step 3: Update ARB files

For each new key, add it to all 4 ARB files. Read each ARB file first to find the right insertion point (alphabetical order is not required, but appending near the end is clean).

Format: add a new line like "keyName": "value", before the closing }.

Step 4: Replace hardcoded strings in Dart files

Replace each hardcoded Chinese string with the appropriate localization call:

• If inside a widget BuildContext: context.appLocalizations.keyName
• If in controller/provider code: currentAppLocalizations.keyName

Ensure the correct import exists:

• For context.appLocalizations: the file should import common.dart (check if it already does)
• For currentAppLocalizations: the file should import app_localizations.dart (check if it already does)

If the file uses string interpolation (e.g., '创建 $name 配置'), convert to the ARB parameterized format:

• In ARB: "keyName": "Create $name config"
• In Dart: currentAppLocalizations.keyName(name)

Step 5: Report changes

After all modifications, output a summary:

1. List each file modified and what changed
2. List each new ARB key added with its translations
3. Remind the user to run code generation if needed:

   dart run build_runner build --delete-conflicting-outputs
   

   or trigger Flutter Intl regeneration in their IDE.

Important notes

• Only extract strings that are user-facing UI text. Do NOT extract:
  • Comments (lines starting with //)
  • Log messages (unless they appear in the UI)
  • Variable names or identifiers
  • String literals used as keys/identifiers (not displayed to users)
• If a Chinese string is split across multiple lines or concatenations, merge them into a single ARB entry
• If a string contains dynamic content (variables, URLs), use ARB parameter syntax $variableName