@harness-engineering/cli 1.6.2 → 1.8.0

package/dist/agents/skills/shared/i18n-knowledge/anti-patterns/formatting.yaml

@@ -0,0 +1,106 @@
+description: "Formatting anti-patterns — common mistakes in number, date, currency, phone, and address formatting across locales"
+
+patterns:
+  - name: "Date formatting without locale"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for toLocaleDateString() without locale argument or manual date string construction"
+      context: "new Date().toLocaleDateString() without first arg, or month + '/' + day + '/' + year concatenation"
+    reason: "Without explicit locale, the runtime's default locale is used — which may differ from the user's locale on servers or CI."
+    instead: "Always pass locale: new Intl.DateTimeFormat(userLocale, options).format(date)"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Number formatting with hardcoded separators"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for regex or replace operations that insert commas or periods as number separators"
+      context: "value.toFixed(2).replace('.', ',') or regex-based thousand separator insertion"
+    reason: "Decimal separator is comma in most of Europe (1.234,56), period in US/UK (1,234.56), and momayyez in Arabic."
+    instead: "Use Intl.NumberFormat(locale).format(value) for all number display"
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "Currency display with hardcoded symbol"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for string concatenation with currency symbols: '$' + amount or amount + ' EUR'"
+      context: "Currency symbol prepended or appended to a formatted number"
+    reason: "Symbol position varies: $100 (en-US), 100 $ (fr-FR), 100$ (pt-BR). Some currencies use code (CHF) not symbol."
+    instead: "Use Intl.NumberFormat(locale, { style: 'currency', currency: code }).format(amount)"
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "Phone number formatting without libphonenumber"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for regex-based phone number formatting or validation"
+      context: "Phone regex like /^\\d{10}$/ or manual formatting with dashes and parentheses"
+    reason: "Phone number formats vary enormously by country. UK: 020 7946 0958. US: (202) 555-0123. Japan: 03-1234-5678."
+    instead: "Use google-libphonenumber for parsing, validation, and formatting; store in E.164 format"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Address formatting with hardcoded field order"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for address string templates that assume a fixed field order"
+      context: "Template like `${street}, ${city}, ${state} ${zip}` used for all countries"
+    reason: "Japan: postal code first, then prefecture, city, street. Germany: street, then postal code + city (same line). Formats vary worldwide."
+    instead: "Use Google's libaddressinput or i18n-postal-address for country-specific address formatting"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Percentage formatting assumptions"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for percentage display constructed by appending '%' to a number"
+      context: "value + '%' or `${value}%` without locale-aware formatting"
+    reason: "Some locales put a space before % (French: 25 %). Turkish uses %25 (prefix). Arabic may use the Arabic percent sign."
+    instead: "Use Intl.NumberFormat(locale, { style: 'percent' }).format(value / 100)"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Hardcoded decimal precision"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for .toFixed(2) applied to currency amounts"
+      context: "Universal 2-decimal-place formatting for all currencies"
+    reason: "JPY and KRW have 0 decimal places. BHD and KWD have 3. Using 2 for all misrepresents amounts."
+    instead: "Use Intl.NumberFormat with currency option which auto-selects correct precision per currency code"
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "Time zone display without IANA identifier"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for timezone abbreviations (EST, PST, CET) in user-facing display"
+      context: "Displaying 'EST' or 'PST' without the full IANA timezone identifier"
+    reason: "Timezone abbreviations are ambiguous (CST = Central Standard Time or China Standard Time) and not universally understood."
+    instead: "Use IANA identifiers (America/New_York) for storage; display user-friendly names via Intl.DateTimeFormat with timeZoneName option"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn

package/dist/agents/skills/shared/i18n-knowledge/anti-patterns/layout.yaml

@@ -0,0 +1,80 @@
+description: "Layout anti-patterns — common mistakes in spatial design, text containers, and directional assumptions that break in localized contexts"
+
+patterns:
+  - name: "Fixed-width containers for text"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for fixed pixel widths on containers that hold translated text"
+      context: "Buttons, labels, or cards with hardcoded width in px that hold user-facing text"
+    reason: "German expands 30-35% over English. Finnish expands up to 40%. Fixed-width containers cause text overflow or truncation."
+    instead: "Use min-width/max-width with flexible layouts; test with the longest target language (typically German or Finnish)"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Hardcoded CSS left/right instead of logical properties"
+    severity: warning
+    scope: web
+    detect:
+      method: "Check for CSS properties using physical directions: margin-left, padding-right, text-align: left, float: left"
+      context: "Layout CSS that uses physical direction properties instead of logical equivalents"
+    reason: "Physical left/right breaks in RTL layouts. margin-left becomes the wrong side for Arabic and Hebrew users."
+    instead: "Use CSS logical properties: margin-inline-start, padding-inline-end, text-align: start, float: inline-start"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Icon placement assumptions"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for icons hardcoded to left or right side of text"
+      context: "Arrow icons, action icons, or navigation indicators with fixed directional placement"
+    reason: "Left-side icons in LTR become wrong-side icons in RTL. But some icons should NOT mirror (checkmarks, media play buttons)."
+    instead: "Use logical placement (inline-start/end); create an icon exception list for icons that should not mirror in RTL"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Text truncation without dir attribute"
+    severity: warning
+    scope: web
+    detect:
+      method: "Check for text-overflow: ellipsis without corresponding dir attribute on the container"
+      context: "Truncated text elements that may contain RTL content"
+    reason: "Ellipsis appears at the wrong end for RTL text without dir attribute. Bidi truncation shows '...مرحبا' instead of 'مرحبا...'"
+    instead: "Set dir attribute on text containers; use CSS direction property in conjunction with text-overflow"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Fixed height on text containers"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for fixed pixel heights on containers that hold multi-line translated text"
+      context: "Cards, tooltips, or modals with hardcoded height that hold translatable content"
+    reason: "Translated text may wrap to more lines due to expansion. Thai and Devanagari need more vertical space for diacritics."
+    instead: "Use min-height instead of height; increase line-height for scripts with stacking diacritics (Thai: 1.8, Devanagari: 1.6)"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Images or graphics containing embedded text"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for images, SVGs, or canvas elements with text baked into the visual"
+      context: "Hero images, infographics, or icons with embedded text labels"
+    reason: "Text in images cannot be translated, searched, or read by screen readers. Each locale requires a new image asset."
+    instead: "Overlay text on images using CSS positioning; use SVG with <text> elements that can reference translation keys"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error

package/dist/agents/skills/shared/i18n-knowledge/anti-patterns/pluralization.yaml

@@ -0,0 +1,80 @@
+description: "Pluralization anti-patterns — common mistakes in handling plural forms across languages with varying CLDR plural categories"
+
+patterns:
+  - name: "Binary plural logic"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for ternary or if/else that only handles singular and plural (two forms)"
+      context: "count === 1 ? singular : plural or count > 1 ? plural : singular"
+    reason: "Many languages need more than two forms. Arabic has 6 (zero, one, two, few, many, other). Polish has 4. Russian has 4. Binary logic covers only English-like languages."
+    instead: "Use ICU MessageFormat plural syntax with all needed CLDR categories: {count, plural, zero {...} one {...} two {...} few {...} many {...} other {...}}"
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "Hardcoded English plural rules applied to all locales"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for plural functions that add 's' suffix or check count === 1"
+      context: "Functions like pluralize(word, count) that append 's' or select between two English forms"
+    reason: "English plural rule (add 's') is specific to English. Most languages have completely different plural morphology."
+    instead: "Delegate pluralization entirely to the i18n framework which implements CLDR plural rules per locale"
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "Missing CLDR plural categories for target locales"
+    severity: error
+    scope: all
+    detect:
+      method: "Check translation files for missing plural category keys compared to what CLDR requires for each locale"
+      context: "Arabic translation file with only 'one' and 'other' forms instead of all 6 required forms"
+    reason: "Missing plural forms cause fallback to 'other' which may be grammatically incorrect for specific counts."
+    instead: "Audit translation files against CLDR plural rules for each target locale; ensure all required categories are present"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Ordinal pluralization not handled"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for ordinal display (1st, 2nd, 3rd) constructed manually or with English-only rules"
+      context: "Appending 'st', 'nd', 'rd', 'th' suffixes based on English ordinal rules"
+    reason: "Ordinal rules vary by locale. English: 1st, 2nd, 3rd. French: 1er, 2e. German: 1., 2. Some languages have no written ordinal form."
+    instead: "Use Intl.PluralRules(locale, { type: 'ordinal' }) to select the correct ordinal form per locale"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Plural forms embedded in UI code instead of message format"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for conditional rendering of plural text in component code rather than translation files"
+      context: "JSX like {count === 1 ? <span>1 item</span> : <span>{count} items</span>}"
+    reason: "Plural logic in code bypasses the translation pipeline. Translators cannot adapt plural forms for their locale."
+    instead: "Move plural selection to translation files using ICU or framework plural syntax; render with a single translation key"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Count-based display without using plural-aware formatter"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for number + noun patterns constructed without plural formatter"
+      context: "Displaying '5 file(s)' or using parenthetical plural as a workaround"
+    reason: "The '(s)' workaround is not grammatical in any language. It looks unprofessional and confuses screen readers."
+    instead: "Use proper plural formatting: t('files', { count: 5 }) with locale-specific plural forms in translation files"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn

package/dist/agents/skills/shared/i18n-knowledge/anti-patterns/string-handling.yaml

@@ -0,0 +1,106 @@
+description: "String handling anti-patterns — common mistakes in text manipulation, concatenation, and string operations that break in localized contexts"
+
+patterns:
+  - name: "String concatenation for sentences"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for string concatenation of user-facing text segments"
+      context: "Expressions like 'Hello, ' + name + '!' or `Welcome to ${place}`"
+    reason: "Word order varies by locale. 'Hello, {name}!' in English becomes '{name}さん、こんにちは！' in Japanese — the name comes first."
+    instead: "Use ICU MessageFormat or framework translation function with named placeholders: t('greeting', { name })"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Hardcoded user-facing strings"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for string literals in JSX, templates, or UI rendering code"
+      context: "Text nodes in JSX, template literals in HTML attributes, string args to UI components"
+    reason: "Untranslated strings are invisible to the localization pipeline. They remain in the source language for all users."
+    instead: "Wrap all user-facing strings in the framework's translation function (t(), $t(), FormattedMessage, etc.)"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error
+
+  - name: "Substring or split on translated strings"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for .substring(), .split(), .slice() applied to translated text"
+      context: "Operations that assume word boundaries or character positions in translated strings"
+    reason: "Word boundaries differ by locale. CJK has no spaces. Thai has no word breaks. Splitting on space fails."
+    instead: "Use Intl.Segmenter for locale-aware text segmentation; redesign to avoid splitting translated text"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Hardcoded plural logic"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for ternary or if/else choosing singular vs plural form"
+      context: "count === 1 ? 'item' : 'items' or similar binary plural selection"
+    reason: "Arabic has 6 plural forms. Polish has 4. Welsh has 6. Binary singular/plural only works for a few languages."
+    instead: "Use CLDR plural rules via ICU MessageFormat: {count, plural, one {# item} other {# items}}"
+    strictness:
+      permissive: warn
+      standard: error
+      strict: error
+
+  - name: "String templates with positional assumptions"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for template literals or format strings that assume a fixed order of interpolated values"
+      context: "Patterns like `${greeting} ${name}` or String.format('%s %s', greeting, name)"
+    reason: "Interpolation order may need to change per locale. Japanese may need name before greeting."
+    instead: "Use named placeholders ({greeting} {name}) so translators can reorder: '{name}さん、{greeting}'"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "UI text in code comments used as display strings"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for display text stored in constants or enums without translation function wrapping"
+      context: "const LABEL = 'Submit' or enum Status { Active = 'Active' } used directly in UI"
+    reason: "Constants and enum values are not extracted by localization tools. They bypass the translation pipeline."
+    instead: "Map enum values to translation keys: const LABELS = { active: t('status.active') }"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "String length validation on translated input"
+    severity: warning
+    scope: all
+    detect:
+      method: "Check for maxLength validation on text that will be translated or on user input from localized forms"
+      context: "Input validation like value.length <= 50 applied to fields that accept multilingual input"
+    reason: "A 50-character limit may be too short for German translations (30-35% expansion) or too long for CJK (visual width differs)."
+    instead: "Use visual width constraints (CSS max-width) instead of character count; adjust limits per locale if needed"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: warn
+
+  - name: "Case transformation without locale"
+    severity: error
+    scope: all
+    detect:
+      method: "Check for .toUpperCase() and .toLowerCase() without locale argument"
+      context: "String case operations that do not use toLocaleUpperCase() or toLocaleLowerCase()"
+    reason: "Turkish dotted-i bug: 'istanbul'.toUpperCase() produces 'ISTANBUL' (wrong) instead of 'ISTANBUL'. German eszett: 'strasse'.toUpperCase() should consider locale."
+    instead: "Always use toLocaleUpperCase(locale) and toLocaleLowerCase(locale) for user-facing text"
+    strictness:
+      permissive: info
+      standard: warn
+      strict: error

package/dist/agents/skills/shared/i18n-knowledge/frameworks/android-resources.yaml

@@ -0,0 +1,47 @@
+name: "Android Resources"
+description: "Android platform localization using XML string resources and the Android resource system"
+platforms: ["mobile"]
+message_format: "custom"
+
+detection:
+  package_json_keys:
+    dependencies: []
+    devDependencies: []
+  file_patterns: ["**/res/values*/strings.xml", "**/*.kt", "**/*.java"]
+  config_files: ["build.gradle", "build.gradle.kts", "AndroidManifest.xml"]
+
+conventions:
+  key_format: "snake_case"
+  file_format: "xml"
+  file_structure: "res/values-{locale}/strings.xml"
+  plural_syntax: "<plurals name='items'><item quantity='one'>%d item</item><item quantity='other'>%d items</item></plurals>"
+  interpolation_syntax: "%s (positional: %1$s, %2$s)"
+
+recommended_tooling:
+  extraction: ["Android Studio translation editor", "Lint checks"]
+  linting: ["Android Lint (MissingTranslation, HardcodedText)"]
+  pseudo_locale: ["Android built-in pseudolocales: en-XA (accented), ar-XB (bidi)"]
+
+anti_patterns:
+  - pattern: "String concatenation instead of getString() with format args"
+    severity: error
+    instead: "Use getString(R.string.greeting, userName) with %1$s placeholders in strings.xml"
+  - pattern: "Hardcoded strings in layout XML"
+    severity: error
+    instead: "Use @string/key references in all android:text and android:hint attributes; Android Lint flags these"
+  - pattern: "Missing quantity entries in <plurals>"
+    severity: error
+    instead: "Include all CLDR quantities for target locales (zero, one, two, few, many, other as applicable)"
+  - pattern: "Using string-array for translatable content without context"
+    severity: warning
+    instead: "Add translatorNote attributes or XML comments for string arrays to provide context for translators"
+  - pattern: "Not using Android pseudolocales for testing"
+    severity: warning
+    instead: "Enable en-XA (accented English) and ar-XB (bidi) pseudolocales in developer settings for testing"
+
+migration_notes:
+  from:
+    - framework: "legacy Java ResourceBundle"
+      guidance: "Move .properties files to Android XML resources; convert MessageFormat patterns to Android format strings; update getString() calls"
+    - framework: "custom key-value solution"
+      guidance: "Map keys to Android resource naming conventions (snake_case); create strings.xml per locale in res/values-{locale}/ directories"

package/dist/agents/skills/shared/i18n-knowledge/frameworks/apple-strings.yaml

@@ -0,0 +1,47 @@
+name: "Apple Strings"
+description: "Apple platform localization using .strings, .stringsdict, and .xcstrings (String Catalogs) files"
+platforms: ["mobile"]
+message_format: "custom"
+
+detection:
+  package_json_keys:
+    dependencies: []
+    devDependencies: []
+  file_patterns: ["**/*.strings", "**/*.stringsdict", "**/*.xcstrings", "**/*.lproj/**"]
+  config_files: ["*.xcodeproj/project.pbxproj", "*.xcworkspace"]
+
+conventions:
+  key_format: "dot-notation"
+  file_format: "strings"
+  file_structure: "{locale}.lproj/Localizable.strings"
+  plural_syntax: ".stringsdict plist format with NSStringLocalizedFormatKey"
+  interpolation_syntax: "%@ (positional: %1$@, %2$@)"
+
+recommended_tooling:
+  extraction: ["genstrings", "Xcode String Catalog auto-extraction"]
+  linting: ["SwiftLint custom rules", "Xcode build warnings"]
+  pseudo_locale: ["xcstrings pseudo-locale generation"]
+
+anti_patterns:
+  - pattern: "Missing .stringsdict for plurals"
+    severity: error
+    instead: "Create .stringsdict files for all pluralized strings; NSLocalizedString alone cannot handle plural forms"
+  - pattern: "Concatenating localized strings"
+    severity: error
+    instead: "Use String(format:) with positional specifiers: String(format: NSLocalizedString('greeting_%@_%@'), firstName, lastName)"
+  - pattern: "Not using String Catalogs (Xcode 15+)"
+    severity: info
+    instead: "Migrate from .strings/.stringsdict to .xcstrings (String Catalogs) for unified translation management"
+  - pattern: "Hardcoded strings in storyboards/XIBs without localization"
+    severity: warning
+    instead: "Use Base Internationalization with .strings files for Interface Builder, or switch to programmatic UI with NSLocalizedString"
+  - pattern: "Not testing with pseudolanguage locale on device"
+    severity: warning
+    instead: "Enable Double-Length Pseudolanguage in Xcode scheme settings to test text expansion"
+
+migration_notes:
+  from:
+    - framework: "legacy .strings"
+      guidance: "Open .strings files in Xcode 15+ and migrate to String Catalogs (.xcstrings); Xcode provides automatic migration; review pluralization rules post-migration"
+    - framework: "third-party (Lokalise SDK, Crowdin SDK)"
+      guidance: "Replace OTA SDK with build-time .xcstrings integration; use export/import workflows instead of runtime translation fetching"

package/dist/agents/skills/shared/i18n-knowledge/frameworks/backend-patterns.yaml

@@ -0,0 +1,50 @@
+name: "Backend Patterns"
+description: "Cross-platform backend i18n patterns for Node.js, Python, Go, and Java server-side localization"
+platforms: ["backend"]
+message_format: "varies"
+
+detection:
+  package_json_keys:
+    dependencies: ["i18next", "i18n-node", "messageformat", "globalize"]
+    devDependencies: []
+  file_patterns: ["**/*.py", "**/*.go", "**/*.java", "**/*.ts", "**/*.js", "**/locales/**", "**/translations/**"]
+  config_files: ["babel.cfg", "locale.go", "messages.properties", "i18n.config.*"]
+
+conventions:
+  key_format: "dot-notation"
+  file_format: "json"
+  file_structure: "locales/{locale}/{namespace}.json"
+  plural_syntax: "Varies by runtime: ICU (Node/Java), gettext (Python), go-i18n (Go)"
+  interpolation_syntax: "Varies: {variable} (ICU), %(variable)s (Python gettext), {{.Variable}} (Go)"
+
+recommended_tooling:
+  extraction: ["i18next-parser (Node)", "pybabel extract (Python)", "go-i18n extract (Go)", "ResourceBundle (Java)"]
+  linting: ["custom CI checks for missing translations"]
+  pseudo_locale: ["pseudo-localization npm package (Node)", "custom generators per platform"]
+
+anti_patterns:
+  - pattern: "Hardcoded error messages in API responses"
+    severity: error
+    instead: "Return error codes with locale-neutral keys; resolve to localized messages on the client or in a localization middleware"
+  - pattern: "Locale detection only from Accept-Language header"
+    severity: warning
+    instead: "Support explicit locale preference (user settings), URL path/query, cookie, then Accept-Language as fallback chain"
+  - pattern: "Storing translated content in code"
+    severity: warning
+    instead: "Externalize translations to resource files (JSON, PO, properties); load at runtime per locale"
+  - pattern: "Email templates with hardcoded language"
+    severity: error
+    instead: "Use locale-aware email template engines; store templates per locale; resolve from user's language preference"
+  - pattern: "Logging in the user's locale instead of a fixed locale"
+    severity: warning
+    instead: "Always log in English (or a fixed locale) for consistent log analysis; localize only user-facing output"
+  - pattern: "Date/time in API responses without timezone"
+    severity: error
+    instead: "Always return ISO 8601 with timezone (UTC preferred) in API responses; let clients format for display locale"
+
+migration_notes:
+  from:
+    - framework: "hardcoded strings"
+      guidance: "Extract all user-facing strings to resource files; implement a translation function (t/gettext); add locale resolution middleware"
+    - framework: "gettext to i18next"
+      guidance: "Convert PO/MO files to JSON format; map gettext plurals to i18next suffix convention; update translation function calls"

package/dist/agents/skills/shared/i18n-knowledge/frameworks/flutter-intl.yaml

@@ -0,0 +1,47 @@
+name: "Flutter Intl"
+description: "Dart/Flutter internationalization using the intl package and ARB (Application Resource Bundle) files"
+platforms: ["mobile"]
+message_format: "icu"
+
+detection:
+  package_json_keys:
+    dependencies: ["flutter_localizations", "intl"]
+    devDependencies: ["intl_utils", "flutter_gen"]
+  file_patterns: ["lib/**/*.dart", "lib/l10n/**/*.arb"]
+  config_files: ["l10n.yaml", "pubspec.yaml"]
+
+conventions:
+  key_format: "camelCase"
+  file_format: "arb"
+  file_structure: "lib/l10n/app_{locale}.arb"
+  plural_syntax: "ICU {count, plural, one {# item} other {# items}}"
+  interpolation_syntax: "{variable}"
+
+recommended_tooling:
+  extraction: ["flutter gen-l10n", "intl_utils"]
+  linting: ["dart analyze"]
+  pseudo_locale: ["custom ARB generator"]
+
+anti_patterns:
+  - pattern: "Hardcoded strings in Text() widgets"
+    severity: error
+    instead: "Use AppLocalizations.of(context)!.messageKey for all user-facing strings"
+  - pattern: "Not running flutter gen-l10n after adding new messages"
+    severity: warning
+    instead: "Run flutter gen-l10n to regenerate the AppLocalizations class after modifying ARB files"
+  - pattern: "Using string interpolation for plurals"
+    severity: error
+    instead: "Use ICU plural syntax in ARB files: {count, plural, one {# item} other {# items}}"
+  - pattern: "Missing @metadata descriptions in ARB files"
+    severity: info
+    instead: "Add @messageKey descriptions for translator context: '@greeting': {'description': 'Welcome message on home screen'}"
+  - pattern: "Not testing with different locale settings on device"
+    severity: warning
+    instead: "Use Flutter integration tests with different locale configurations; test RTL with Arabic locale"
+
+migration_notes:
+  from:
+    - framework: "easy_localization"
+      guidance: "Convert JSON translation files to ARB format; replace tr() calls with AppLocalizations.of(context); update locale loading configuration in MaterialApp"
+    - framework: "get (GetX i18n)"
+      guidance: "Move from Map-based translations to ARB files; replace 'key'.tr with AppLocalizations; configure locale resolution in MaterialApp.localizationsDelegates"

package/dist/agents/skills/shared/i18n-knowledge/frameworks/i18next.yaml

@@ -0,0 +1,47 @@
+name: "i18next"
+description: "Full-featured i18n framework with plugins for React, Vue, Node, and many other platforms"
+platforms: ["web", "mobile", "backend"]
+message_format: "i18next"
+
+detection:
+  package_json_keys:
+    dependencies: ["i18next", "react-i18next", "next-i18next", "i18next-http-backend", "i18next-browser-languagedetector"]
+    devDependencies: ["i18next-parser", "i18next-scanner"]
+  file_patterns: ["src/**/*.{ts,tsx,js,jsx}", "public/locales/**/*.json"]
+  config_files: ["i18next.config.js", "i18next.config.ts", "next-i18next.config.js"]
+
+conventions:
+  key_format: "nested"
+  file_format: "json"
+  file_structure: "public/locales/{locale}/{namespace}.json"
+  plural_syntax: "key_one: '# item', key_other: '# items' (suffix-based)"
+  interpolation_syntax: "{{variable}}"
+
+recommended_tooling:
+  extraction: ["i18next-parser", "i18next-scanner"]
+  linting: ["eslint-plugin-i18next"]
+  pseudo_locale: ["i18next-pseudo"]
+
+anti_patterns:
+  - pattern: "Not using the count option for pluralization"
+    severity: error
+    instead: "Pass { count: n } to t() function: t('items', { count: itemCount }) — i18next auto-selects the plural form"
+  - pattern: "Nesting translations with $t() inside translations"
+    severity: warning
+    instead: "Use flat interpolation or context-based keys instead of nested $t() references which are hard to extract"
+  - pattern: "Loading all namespaces upfront"
+    severity: warning
+    instead: "Use lazy loading with i18next-http-backend to load namespaces on demand for better performance"
+  - pattern: "Hardcoding the fallback language in multiple places"
+    severity: warning
+    instead: "Configure fallbackLng once in i18next.init(); use namespace-level fallbacks for granular control"
+  - pattern: "Using the t() function outside React components without proper initialization"
+    severity: error
+    instead: "Use i18next.t() directly for non-React code, or pass the t function from initialized context"
+
+migration_notes:
+  from:
+    - framework: "react-intl"
+      guidance: "Convert ICU {variable} to {{variable}}; convert ICU plural syntax to suffix-based keys (_one, _other); replace FormattedMessage with useTranslation() hook"
+    - framework: "custom-solution"
+      guidance: "Map existing key-value pairs to i18next namespace structure; configure fallback chains; add language detection plugin"