# Harness I18N > Harness i18n - Skill: `intense-visions/harness-i18n` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add intense-visions/harness-i18n` - Raw SKILL.md: https://api.skillmd.com/api/skills/intense-visions/harness-i18n/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Intense-Visions (https://skillmd.com/u/intense-visions) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/intense-visions/harness-i18n --- # Harness i18n > Internationalization compliance verification. Detect hardcoded strings, missing translations, locale-sensitive formatting, RTL issues, and concatenation anti-patterns across web, mobile, and backend codebases. ## When to Use - Auditing new or existing codebases for i18n compliance - Before PR merge to catch i18n regressions - When `on_pr` or `on_commit` triggers fire and changes touch user-facing strings - When translation files change (missing keys, untranslated values) - After adding a new target locale to verify coverage - When `on_review` triggers fire to validate i18n considerations - NOT for setting up translation infrastructure (use harness-i18n-workflow) - NOT for injecting i18n into brainstorming/planning (use harness-i18n-process) - NOT for performing translations (use TMS tools or MCP integrations) - NOT for non-user-facing code (internal logging, debug messages, developer tooling) ## Process ### Phase 1: DETECT -- Identify i18n Context 1. **Read harness configuration.** Check `harness.config.json` for `i18n` block: - `i18n.enabled` -- master toggle (if false or missing, run in discovery mode: detect but do not enforce) - `i18n.strictness` -- enforcement level (`strict`, `standard`, `permissive`) - `i18n.sourceLocale` -- BCP 47 code of source language (default: `en`) - `i18n.targetLocales` -- array of BCP 47 codes for target languages - `i18n.framework` -- `auto` or specific framework name - `i18n.platforms` -- which platforms to scan (`web`, `mobile`, `backend`) - `i18n.coverage` -- coverage thresholds and requirements 2. **Auto-detect project platform(s).** Scan project root for: - Web: `package.json` with React/Vue/Svelte/Next/Nuxt deps, `.tsx`/`.jsx`/`.vue`/`.svelte` files - Mobile iOS: `*.xcodeproj`, `Podfile`, `Package.swift`, `.swift` files - Mobile Android: `build.gradle`/`build.gradle.kts`, `AndroidManifest.xml`, `.kt`/`.java` files - Mobile Flutter: `pubspec.yaml` with `flutter` dependency, `.dart` files - Backend: `package.json` with Express/Fastify/NestJS, `requirements.txt`/`pyproject.toml`, `go.mod`, `pom.xml`/`build.gradle` 3. **Auto-detect i18n framework.** Read framework detection profiles from `agents/skills/shared/i18n-knowledge/frameworks/`. For each profile, check: - `detection.package_json_keys` -- dependencies and devDependencies in `package.json` - `detection.config_files` -- presence of framework config files - `detection.file_patterns` -- translation file patterns - Match the first profile that satisfies detection criteria. If none match, record "no i18n framework detected." 4. **Locate existing translation files.** Search for: - JSON files in `locales/`, `src/locales/`, `public/locales/`, `assets/translations/` - `.strings` and `.stringsdict` files (iOS) - `res/values*/strings.xml` (Android) - `.arb` files (Flutter) - PO/POT files (gettext) - If `i18n.translationPaths` is configured, use those paths instead. 5. **Load locale profiles.** For each locale in `i18n.targetLocales` (or detected from translation files), read the locale profile from `agents/skills/shared/i18n-knowledge/locales/{locale}.yaml`. This provides: plural rules, text direction, expansion factor, script characteristics, common pitfalls. 6. **Load industry profile.** If `i18n.industry` is configured, read `agents/skills/shared/i18n-knowledge/industries/{industry}.yaml` for industry-specific rules. 7. **Report detection results before proceeding:** ``` i18n Detection Report ===================== Config: Found (i18n.enabled: true, strictness: standard) Platform(s): web, backend Framework: i18next (detected from package.json) Translation files: public/locales/{en,es,fr}/*.json (3 locales, 4 namespaces) Source locale: en Target locales: es, fr Industry profile: fintech (loaded) ``` ### Phase 2: SCAN -- Detect i18n Violations 1. **Determine scan scope.** Based on detected platforms, select file patterns: - Web: `**/*.{tsx,jsx,vue,svelte,html}` and `**/*.{ts,js}` (for template literals in rendering code) - Mobile iOS: `**/*.swift` - Mobile Android: `**/*.{kt,java}`, `**/res/values*/*.xml` - Mobile Flutter: `**/*.dart` - Backend: `**/*.{ts,js,py,go,java}` (filtered to HTTP handlers, templates, email services) - Exclude: `node_modules`, `build`, `dist`, `.next`, `vendor`, `Pods`, test files (unless explicitly included) 2. **Scan for hardcoded user-facing strings.** For each platform, apply these detection rules: _Web (React/Vue/Svelte/vanilla):_ - `I18N-001` String literals in JSX text content (text nodes between tags) - `I18N-002` String literals in i18n-sensitive props: `title`, `placeholder`, `alt`, `aria-label`, `aria-description` - `I18N-003` Template literals with user-facing text in JSX or template expressions - Exclude: CSS class names, data attributes, event names, `key` prop, `id`, `data-testid`, `className`, `style`, `type`, `role`, `htmlFor`, `ref`, numeric literals, boolean props, import/require paths _Mobile iOS (SwiftUI/UIKit):_ - `I18N-011` String literals in `Text()`, `Label()`, `Alert()`, `.navigationTitle()`, `.toolbar` labels - `I18N-012` String literals in `UILabel.text`, `UIButton.setTitle`, `UIAlertController` messages - Exclude: SF Symbol names, asset names, notification names, UserDefaults keys _Mobile Android (Compose/Views):_ - `I18N-021` String literals in `Text()`, `TextField()`, `Button()` content - `I18N-022` String literals in `setText()`, `setTitle()`, `Toast.makeText()` - Exclude: Log tags, intent actions, preference keys, layout identifiers _Mobile Flutter:_ - `I18N-031` String literals in `Text()`, `TextSpan()`, `AppBar(title:)`, `SnackBar(content:)` - Exclude: route names, asset paths, key values _Backend:_ - `I18N-041` String literals in HTTP response bodies (`res.json({ message: '...' })`, `res.send('...')`) - `I18N-042` String literals in email template content (detected via email service imports) - `I18N-043` String literals in notification payloads - Exclude: log messages (unless returned to users), internal error codes, header names, route paths 3. **Scan for locale-sensitive formatting.** - `I18N-101` `new Date().toLocaleDateString()` without explicit locale argument - `I18N-102` `Number.toFixed()`, `.toLocaleString()` without locale argument - `I18N-103` Hardcoded currency symbols (`$`, `EUR`, etc.) in string templates - `I18N-104` Hardcoded decimal separators (`.` for decimal, `,` for thousands) - `I18N-105` `new Intl.DateTimeFormat()` or `new Intl.NumberFormat()` without locale parameter (using implicit browser locale is often a bug) 4. **Scan for missing `lang`/`dir` attributes.** - `I18N-201` Missing `lang` attribute on `` element - `I18N-202` Missing `dir` attribute on `` element (required when any target locale is RTL) - `I18N-203` Missing `dir="auto"` on user-generated content containers (detected via heuristic: elements rendering user input, comments, messages) - `I18N-204` Hardcoded `left`/`right` in CSS or style props instead of logical properties (`start`/`end`, `inline-start`/`inline-end`) -- only flagged when RTL locales are in target list 5. **Scan for string concatenation.** - `I18N-301` String concatenation to build user-facing messages (`"Hello, " + name`, `` `Welcome ${name}` `` used as complete messages) - `I18N-302` Array `.join()` to build sentences or messages - `I18N-303` Conditional text assembly (`isPlural ? "items" : "item"` -- hardcoded plural logic) - Provide framework-specific alternative in the finding (e.g., for i18next: `t('greeting', { name })`) 6. **Scan translation files for completeness.** - `I18N-401` Missing keys: keys present in source locale file but absent in target locale file - `I18N-402` Untranslated values: values in target locale file identical to source locale (suggesting copy-paste, not translation) - `I18N-403` Missing plural forms: for each locale, check that all required CLDR plural categories are present. Load plural rules from locale profile (e.g., Arabic requires: zero, one, two, few, many, other). - `I18N-404` Empty translation values (key exists but value is empty string) - `I18N-405` Orphan keys: keys in translation files not referenced in source code (requires cross-referencing with source scan) 7. **Record all findings.** Each finding includes: - File path - Line number (approximate, from Grep output) - Violation code (e.g., `I18N-001`) - Category: `strings`, `formatting`, `attributes`, `concatenation`, `translations` - Element or pattern that triggered the finding - Raw evidence (the matching line of code) ### Phase 3: REPORT -- Generate i18n Report 1. **Assign severity based on `i18n.strictness`:** - `strict` mode: all violations are `error` severity - `standard` mode: hardcoded strings and missing translations are `error`; formatting and concatenation are `warn`; orphan keys and info patterns are `info` - `permissive` mode: missing translations and hardcoded strings are `warn`; everything else is `info` - Discovery mode (unconfigured): all findings are `info` 2. **Generate summary header:** ``` i18n Report =========== Scanned: 87 source files, 12 translation files Findings: 24 total (8 error, 12 warn, 4 info) Strictness: standard Framework: i18next Platforms: web, backend Locales: en (source), es, fr (targets) ``` 3. **List findings grouped by category.** Each finding follows this format: ``` I18N-001 [error] Hardcoded string in JSX text content File: src/components/Header.tsx Line: 12 Element:

Welcome to our platform

Category: strings Fix: Wrap in translation:

{t('header.welcome')}

``` ``` I18N-401 [error] Missing translation key File: public/locales/es/common.json Key: checkout.summary.totalLabel Source: "Total" (en) Category: translations Fix: Add key to es/common.json with Spanish translation ``` 4. **Provide category summaries** with counts and severity breakdown: ``` Category Breakdown ------------------ Strings: 12 findings (6 error, 4 warn, 2 info) Translations: 6 findings (4 error, 2 warn) Formatting: 3 findings (0 error, 3 warn) Attributes: 2 findings (1 error, 1 warn) Concatenation: 1 finding (0 error, 1 warn) ``` 5. **Provide translation coverage summary** (if translation files exist): ``` Translation Coverage -------------------- Locale Keys Translated Coverage Missing Plurals en 142 142 100% 0 es 142 128 90.1% 2 fr 142 135 95.1% 0 ``` 6. **If graph is available** (`.harness/graph/` exists): map findings to components/routes for contextual coverage. Report per-component translation coverage. 7. **If graph is unavailable**: report per-file key-level coverage. Group findings by source file. 8. **List actionable next steps:** - Errors that can be auto-fixed (Phase 4) - Errors that require human judgment (choosing translation keys, writing translations) - Warnings to address in next iteration - Coverage gaps to escalate to translation workflow (harness-i18n-workflow) ### Phase 4: FIX -- Apply Automated Remediation (Optional) This phase is optional. It applies fixes only for mechanical issues -- violations with a single, unambiguous correct fix. Translation content, key naming, and locale-specific formatting choices are never auto-fixed. 1. **Fixable violations:** - `I18N-001`/`I18N-002`: Wrap string literals in framework translation call. Detect framework from Phase 1: - i18next: `{t('generated.key')}` (generate key from string content, dot-notation) - react-intl: `` - vue-i18n: `{{ $t('generated.key') }}` - No framework: `{t('generated.key')}` (generic, user picks framework later) - `I18N-201`: Add `lang="{sourceLocale}"` to `` element - `I18N-202`: Add `dir="ltr"` (or `dir="auto"` if RTL locales are targets) to `` element - `I18N-203`: Add `dir="auto"` to user-content containers - `I18N-404`: Flag empty translation values for review (not auto-fillable) 2. **Apply each fix as a minimal, targeted edit.** Use the Edit tool. Do not refactor surrounding code. Do not change formatting. The fix should be the smallest possible change that resolves the violation. 3. **Show before/after diff for each fix.** Present the exact change to the user. This is a hard gate -- no fix is applied without showing the diff first. 4. **Interactive confirmation per fix category.** Group fixes by category (string wrapping, attribute addition) and ask for approval per category, not per individual fix: ``` Fix Category: String Wrapping (12 fixes) ----------------------------------------- Wrap 12 hardcoded strings in t() calls across 5 files. Generated keys follow dot-notation: component.element.description Apply these fixes? [y/n] ``` 5. **Generate extraction output.** For each wrapped string, output the key-value pair that needs to be added to the source locale translation file: ```json { "header.welcome": "Welcome to our platform", "checkout.totalLabel": "Total", "auth.loginButton": "Sign in" } ``` 6. **Re-scan after fixes.** Run the scan phase again on fixed files to confirm violations are resolved. Report: - Fixes applied: N - Violations resolved: N - Keys extracted: N (add to source locale file) - Remaining violations (require human judgment): M 7. **Do NOT fix:** - Translation content (requires human translators or TMS) - Key naming beyond generated defaults (requires project context) - Locale-sensitive formatting (requires knowing the correct Intl API usage for each case) - Plural form additions (requires CLDR knowledge + framework-specific syntax) - Any fix that would change the runtime behavior of the application ## Harness Integration - **`harness validate`** -- i18n findings surface when `i18n.enabled` is true and `i18n.strictness` is `strict` or `standard`. Running validate after a scan reflects the current i18n state. - **`harness-integrity`** -- The i18n scan is chained into integrity checks when `i18n.enabled: true`. Findings are included in the unified integrity report. - **`harness-release-readiness`** -- Translation coverage is checked against `i18n.coverage.minimumPercent`. Per-locale coverage is reported. - **`harness-accessibility`** -- When both i18n and accessibility skills are enabled, `lang`/`dir` attribute checks are handled by the i18n skill. The accessibility skill defers I18N-201/202/203 to avoid duplicate findings. - **`harness-i18n-workflow`** -- After scanning, coverage gaps and extracted keys can be passed to the workflow skill for scaffolding and translation file updates. - **Knowledge base** at `agents/skills/shared/i18n-knowledge/` -- Framework profiles, locale profiles, industry profiles, and anti-pattern catalogs are consumed during detect and scan phases. ## Success Criteria - All scanned source files have findings categorized by violation code and severity - Hardcoded user-facing strings detected with correct platform-specific rules (web, mobile, backend) - Missing translation keys and untranslated values identified with file paths and key names - Locale-sensitive formatting issues (dates, numbers, currencies) flagged with specific file and line references - RTL and `lang`/`dir` attribute violations detected when target locales include RTL languages - String concatenation and hardcoded plural logic identified as anti-patterns - Report generated with violation codes, categories, severity, and actionable remediation - Automated fixes applied only for mechanical issues (string wrapping, attribute addition) with interactive confirmation - Translation coverage reported per-locale against configured thresholds - `harness validate` reflects i18n findings at the configured strictness level ## Examples ### Example: Scanning a React + i18next Project **Context:** A React web app using i18next with English source, targeting Spanish and French. The `harness.config.json` has: ```json { "version": 1, "i18n": { "enabled": true, "strictness": "standard", "sourceLocale": "en", "targetLocales": ["es", "fr"], "framework": "auto", "platforms": ["web"] } } ``` **Phase 1: DETECT** ``` i18n Detection Report ===================== Config: Found (i18n.enabled: true, strictness: standard) Platform(s): web Framework: i18next (detected from package.json: "i18next", "react-i18next") Translation files: public/locales/{en,es,fr}/common.json (3 locales, 1 namespace) Source locale: en Target locales: es, fr Industry profile: none configured ``` **Phase 2: SCAN** Source file with violations: ```tsx // src/components/CheckoutSummary.tsx export function CheckoutSummary({ items, total }) { return (

Order Summary

You have {items.length} {items.length === 1 ? 'item' : 'items'} in your cart.

Total: ${total.toFixed(2)}
); } ``` Findings: ``` I18N-001 [error] Hardcoded string in JSX text content File: src/components/CheckoutSummary.tsx Line: 5 Element:

Order Summary

Category: strings Fix: Wrap in translation:

{t('checkout.orderSummary')}

I18N-002 [error] Hardcoded string in i18n-sensitive prop File: src/components/CheckoutSummary.tsx Line: 9 Element: title="Total price" Category: strings Fix: Wrap in translation: title={t('checkout.totalPriceTitle')} I18N-303 [warn] Conditional text assembly (hardcoded plural logic) File: src/components/CheckoutSummary.tsx Line: 7 Element: items.length === 1 ? "item" : "items" Category: concatenation Fix: Use i18next plural: t('checkout.itemCount', { count: items.length }) I18N-103 [warn] Hardcoded currency symbol File: src/components/CheckoutSummary.tsx Line: 10 Element: $${total.toFixed(2)} Category: formatting Fix: Use Intl.NumberFormat: new Intl.NumberFormat(locale, { style: 'currency', currency }).format(total) I18N-102 [warn] Number.toFixed() without locale-aware formatting File: src/components/CheckoutSummary.tsx Line: 10 Element: total.toFixed(2) Category: formatting Fix: Use Intl.NumberFormat for locale-aware decimal formatting ``` Translation file issue: ``` I18N-401 [error] Missing translation key File: public/locales/es/common.json Key: checkout.confirmButton Source: "Confirm Order" (en) Category: translations Fix: Add key to es/common.json with Spanish translation I18N-402 [warn] Untranslated value (identical to source) File: public/locales/fr/common.json Key: auth.welcomeMessage Source: "Welcome back" (en) Value: "Welcome back" (fr -- same as source, likely untranslated) Category: translations Fix: Translate value to French or mark as intentionally identical ``` **Phase 3: REPORT** ``` i18n Report =========== Scanned: 23 source files, 6 translation files Findings: 7 total (3 error, 3 warn, 1 info) Strictness: standard Framework: i18next Platforms: web Locales: en (source), es, fr (targets) Category Breakdown ------------------ Strings: 2 findings (2 error, 0 warn) Translations: 2 findings (1 error, 1 warn) Formatting: 2 findings (0 error, 2 warn) Concatenation: 1 finding (0 error, 1 warn) Translation Coverage -------------------- Locale Keys Translated Coverage Missing Plurals en 42 42 100% 0 es 42 41 97.6% 0 fr 42 42 100% 0 (note: fr has 1 untranslated value not counted as missing) ``` **Phase 4: FIX** ``` Fix Category: String Wrapping (2 fixes) ----------------------------------------- Wrap 2 hardcoded strings in t() calls in CheckoutSummary.tsx. Generated keys: checkout.orderSummary, checkout.totalPriceTitle Apply these fixes? [y/n] ``` After applying fixes: ```diff -

Order Summary

+

{t('checkout.orderSummary')}

- + ``` Keys extracted for source locale file: ```json { "checkout.orderSummary": "Order Summary", "checkout.totalPriceTitle": "Total price" } ``` Remaining violations (require human judgment): 5 - I18N-303: Plural logic -- requires choosing i18next plural key structure - I18N-103: Currency symbol -- requires knowing the correct currency code per locale - I18N-102: Number formatting -- requires choosing Intl.NumberFormat options - I18N-401: Missing key in es -- requires Spanish translation - I18N-402: Untranslated value in fr -- requires French translation ## Rationalizations to Reject | Rationalization | Reality | | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "This string is the app's brand name — it's technically hardcoded but obviously shouldn't be translated. I'll skip flagging it." | Brand names require explicit suppression via `// i18n-ignore` comment, not silent omission from the scan. Skipping without suppression means future scans have inconsistent results and the team has no record of the deliberate decision. | | "The framework isn't in the knowledge base, but I can tell from context it's using i18next patterns — I'll apply i18next rules directly." | Unrecognized frameworks must fall back to generic detection rules, not assumed framework rules. Applying i18next-specific fix patterns to an unknown framework produces incorrect wrapping that breaks at runtime. Log the gap and use generic rules. | | "The project has `i18n.enabled: false` — I'll still flag errors for hardcoded strings since the team should know about them." | Respecting `i18n.enabled: false` is a gate. The team made a configuration decision. In that state, run in discovery mode (info severity only). Escalating to errors overrides the team's explicit choice. | | "I18N-402 untranslated values are just warnings — I'll skip reporting them to keep the report shorter." | Untranslated values (target identical to source) are a distinct violation category with their own code. They indicate copy-paste during file creation without actual translation. Omitting them produces a misleadingly optimistic coverage report. | | "The plural rules for this locale look complex — I'll just check for 'one' and 'other' forms like English and move on." | Plural rules are locale-specific and must be loaded from the locale profile. Arabic requires six categories; Polish requires four. Checking only English plural categories produces false-passing results for languages that require more forms. | ## Gates These are hard stops. Violating any gate means the process has broken down. - **No scan results without completing the detect phase first.** Framework and platform detection must run before scanning begins. - **No fix applied without showing the before/after diff.** Every fix must be presented to the user with the exact code change before being written to disk. - **No severity downgrade below what `i18n.strictness` specifies.** If the project is in `strict` mode, a hardcoded string is an error. The scanner does not get to decide it is a warning. - **No translation content generated by the fix phase.** The fix phase wraps strings and adds attributes. It does not write translations. Translation content is the domain of humans or TMS tools. - **No false-positive suppression without explicit user confirmation.** If a string is intentionally not translated (e.g., brand name), the user must mark it with a suppression comment (`// i18n-ignore`) before it is excluded from future scans. ## Escalation - **When a project has more than 100 hardcoded strings:** suggest running harness-i18n-workflow for bulk extraction and scaffolding rather than fixing one by one. - **When no i18n framework is detected:** recommend one based on the project platform (i18next for React/Node, vue-i18n for Vue, flutter intl for Flutter, etc.). Reference the framework profiles in the knowledge base. - **When translation coverage is below 50%:** suggest a phased approach -- prioritize user-facing flows (checkout, onboarding, error messages) before attempting full coverage. - **When target locales include RTL languages (ar, he) and the project has no RTL support:** flag this as a high-priority architectural concern. RTL support often requires layout changes beyond simple attribute additions. - **When the project uses a framework not in the knowledge base:** fall back to generic detection rules. Log: "Framework {name} not in knowledge base -- using generic string detection. Consider contributing a framework profile."