Internationalization (i18n) Rules

---
description: Guidelines for i18n
globs: **/*
---

# Internationalization (i18n) Rules

Rules for managing internationalization in the Wox project.

<rule>
name: i18n_standards
description: Standards for internationalization implementation in Wox
filters:
  # Match any source files that might contain UI text
  - type: file_extension
    pattern: "\\.(go|dart|js|ts|vue|html)$"
  # Match string literals that might need i18n
  - type: content
    pattern: '"[^"]*"'
  # Match code changes that add new text
  - type: event
    pattern: "file_modify"

actions:
  - type: reject
    conditions:
      # Reject hardcoded UI strings
      - pattern: '(?<!tr\\()](mdc:wox/[\w\s]+)["\']'
        message: "UI strings should use tr() function"

      # Reject direct use of error messages
      - pattern: 'errors\\.New\\("[^"]+"\\)'
        message: "Error messages should be internationalized"

      # Reject trParams usage
      - pattern: '\\.trParams\\('
        message: "Use Strings.format instead of trParams"

      # Reject const with tr()
      - pattern: 'const.*tr\\('
        message: "Cannot use tr() in const expressions"

  - type: suggest
    message: |
      When implementing internationalization:

      1. String Translation Keys:
         - Use descriptive, hierarchical keys: `category_subcategory_action`
         - Example: `setting_plugin_install`
         - Keep keys in English, lowercase with underscores
         - For Dart/Flutter code: Do NOT add `ui_` prefix, it's automatically added by tr() method
         - For Go code: Use the key directly without `ui_` prefix

      2. Translation Files:
         - Place in `wox.core/resource/lang/`
         - Use JSON format with nested structure
         - All keys in translation files should have `ui_` prefix for Dart/Flutter UI strings
         - Translation File Organization:
           ┌─────────────────────────────────┐
           │ 1. UI Translations (ui_*)       │ ← Add new UI translations here
           │    - ui_general                 │
           │    - ui_settings               │
           │    ...                         │
           ├─────────────────────────────────┤
           │ 2. Non-UI Translations         │ ← Add new non-UI translations here
           │    - plugin_*                  │
           │    - error_*                   │
           │    ...                         │
           └─────────────────────────────────┘
         - When updating translation files:
           * ALL language files must be updated together
           * Check all files under `wox.core/resource/lang/` directory
           * Keep keys consistent across all language files
           * Never leave any language file with missing translations

      3. In Go Code:
         - Use `i18n.GetI18nManager().TranslateWox(ctx, "key")`
         - For variables: `fmt.Sprintf(i18n.GetI18nManager().TranslateWox(ctx, "key"), vars...)`
         - Use the key directly without `ui_` prefix

      4. In Dart/Flutter Code:
         - Use `controller.tr('key')` (no need to add ui_ prefix)
         - For variables: `Strings.format(controller.tr('key'), [vars])`
         - The `ui_` prefix is automatically added by tr() method
         - NEVER use trParams(), always use Strings.format()
         - NEVER use const with widgets that contain tr() calls
         - If a parent widget contains children with tr() calls, the parent cannot be const

      5. Do NOT Translate:
         - Log messages
         - Debug information
         - Comments
         - Plugin names and authors
         - Technical terms

      6. Always provide:
         - English (en_US) as base language
         - Context comments for translators
         - Placeholder explanations

      7. Implementation Checklist:
         Before submitting changes, verify:
         □ All text strings use tr()
         □ All variable text uses Strings.format()
         □ No trParams() usage
         □ No const on widgets with tr()
         □ No const on parent widgets containing tr()
         □ Translation keys follow naming convention
         □ All language files are updated
         □ All translations are consistent across languages

      8. Adding New Translations:
         Step 1: Identify the type of translation
         □ Is it a UI string? (Will use ui_ prefix)
         □ Is it a non-UI string? (Will use plugin_, error_, etc. prefix)

         Step 2: Locate the correct section
         □ UI translations: Add after similar UI keys at the beginning
         □ Non-UI translations: Add after similar non-UI keys after all UI translations
         □ Group similar functionality together

         Step 3: Update all language files
         □ Add the key in the same position in all files
         □ Ensure translations are provided for all languages
         □ Verify the grouping is maintained

         Step 4: Verify
         □ Keys are properly grouped
         □ Placement is consistent across all files
         □ No existing groups are broken

      9. Quick Checklist for Adding Translations:
          □ Is it a UI translation? → Place in UI section
          □ Is it a non-UI translation? → Place in non-UI section
          □ Are similar keys grouped together?
          □ Is the placement consistent across all language files?
          □ Have you updated ALL language files?

examples:
  - input: |
      // Bad: Mixed UI and non-UI translations
      {
        "plugin_name": "My Plugin",
        "ui_settings": "Settings",
        "error_msg": "Error",
        "ui_general": "General"
      }

      // Good: Grouped UI and non-UI translations
      {
        "ui_general": "General",
        "ui_settings": "Settings",

        "error_msg": "Error",
        "plugin_name": "My Plugin"
      }
    output: "Properly organized translation file"

  - input: |
      // Bad: Adding new UI translation at the end
      {
        "ui_general": "General",
        "plugin_name": "My Plugin",
        "ui_new_feature": "New Feature"  // ❌ Wrong placement
      }

      // Good: Adding new UI translation in UI section
      {
        "ui_general": "General",
        "ui_new_feature": "New Feature",  // ✅ Correct placement

        "plugin_name": "My Plugin"
      }
    output: "Correct placement of new translations"

metadata:
  priority: high
  version: 1.3