i18n-localization-engineering

---
name: i18n-localization-engineering
description: Use for any task involving internationalization, localization, translation catalogs, language switching, locale detection, React user-facing text, tooltips, accessibility labels, errors, notifications, date and number formatting, native Tauri menus, regional conventions, right-to-left readiness, or localization testing. Also use when reviewing UI changes for missing translations or auditing locale completeness.
---

# Clypra Internationalization and Localization Engineering

## Use When

Activate this skill whenever a task:

* Adds, modifies, removes, or reviews application-owned user-facing text.

* Changes a React component, UI primitive, tooltip, menu, dialog, notification, or error message.

* Modifies supported languages, translation catalogs, language selection, fallback, or persisted preferences.

* Changes native Tauri menus, Rust-generated messages, frontend/backend error contracts, or OS integration involving text.

* Changes accessibility labels, descriptions, announcements, placeholders, or document titles.

* Introduces locale-dependent formatting, pluralization, interpolation, sorting, dates, numbers, or units.

* Changes keyboard shortcut descriptions, help text, onboarding, or contextual instructions.

* Changes project or media metadata displayed to the user.

* Requires localization audits, translation quality improvements, or localization regression tests.

The skill also applies during code review when a change introduces user-facing text or alters an existing localization contract.

## Don't Use When

* A change is exclusively internal and cannot affect any user-visible or assistive-technology-visible behavior. Still inspect adjacent localization implications when uncertain.

* A task concerns general application architecture without localization consequences. Use the architecture-design-review skill instead.

* A task concerns generic UI layout without text, accessibility, or locale implications. Use the applicable frontend and UI testing skills.

* A task concerns only linguistic review of provided text with no repository or software changes.

When multiple concerns apply, combine this skill with the relevant implementation, architecture, accessibility, behavior-testing, Playwright, Tauri cross-platform, and code-review skills.

## Workflow

### 1. Inspect the existing localization architecture

Before making changes, inspect the current implementation.

Establish:

* The localization library or custom implementation.

* The canonical locale and translation resource structure.

* The supported locale identifiers.

* The translation API exposed to React components.

* Locale fallback and missing-key behavior.

* Language preference persistence and initial detection.

* Interpolation and pluralization behavior.

* Date, number, and duration formatting.

* Native Tauri menu and Rust message handling.

* Catalog validation and existing tests.

* CI commands that enforce localization requirements.

Read the affected components and their relevant consumers.

Do not assume that reported documentation, dictionary sizes, passing tests, or the existence of an internationalization library proves comprehensive localization coverage.

### 2. Inspect the affected user-facing surfaces

Determine which text the change introduces or affects.

Consider all application-owned text that users can see, hear through assistive technology, or interact with, including:

* Headings, labels, buttons, links, menus, tabs, and context menus.

* Tooltips, hover descriptions, and title attributes.

* Placeholders, form validation, confirmation dialogs, and warnings.

* Loading indicators, progress descriptions, empty states, and notifications.

* Application-owned error and recovery messages.

* Accessibility names, descriptions, and screen-reader announcements.

* Dynamic status text and interpolated messages.

* Document titles and application-owned window titles.

* Timeline controls, track labels, media metadata, and export status.

* Text generated by canvas, SVG, custom rendering, or imperative DOM code.

* Strings produced by background tasks or received from native commands.

* Native menu labels and relevant operating-system integration.

Inspect nested dialogs, portals, popovers, and components mounted conditionally.

Do not rely exclusively on searching for string literals. Follow the relevant render paths and data flow.

Distinguish application-owned text from OS-owned or externally provided content. Document genuine limitations instead of claiming that every system dialog can be controlled by Clypra's language preference.

### 3. Define the required behavior before changing code

Identify the appropriate localization contract for the change.

Consider:

* What should the user see in every supported locale?

* Which values are translated and which must remain unchanged?

* Does the text contain dynamic data?

* Are plural forms or grammatical context required?

* Can the translated text become substantially longer?

* Does it affect tooltips, accessibility, keyboard navigation, or dialogs?

* Does the locale affect formatting or interpretation?

* Does the change cross a frontend, Rust, or native menu boundary?

* Which fallback behavior should apply?

* What could regress when the language changes at runtime?

Identify relevant edge cases before implementation and perform an independent post-implementation audit afterward.

Use the behavior-testing skill for detailed scenario enumeration and the Playwright skill for applicable user-interface workflows.

### 4. Preserve a coherent canonical translation model

Use the actual repository's established localization architecture.

For a semantic-key-based architecture, use stable identifiers representing the meaning of a message, rather than English wording as the permanent identifier.

For example:

* `settings.language.label`

* `timeline.actions.split`

* `timeline.tooltips.split`

* `preview.errors.audioUnavailable`

* `export.status.rendering`

* `accessibility.playback.pause`

These are illustrative naming conventions, not mandatory identifiers.

English should serve as the canonical source catalog unless the repository has a justified alternative.

Every supported locale must implement the required message contract, subject to explicit and documented exceptions.

Do not introduce a second translation architecture or duplicate catalogs without a clear migration plan.

If the application uses a custom localization implementation, evaluate it on correctness, maintainability, compatibility, and testability before replacing it.

Do not introduce a new dependency solely for popularity or stylistic preference.

Do not use English reverse dictionaries or DOM mutation as the primary long-term source of truth when semantic translation resources and normal component rendering can provide a more reliable contract.

If a legacy migration is necessary, preserve working behavior incrementally and test the transition.

### 5. Implement localization correctly in React

New application-owned user-facing strings must use the repository's canonical localization API.

Do not hard-code English user-facing strings in components when the canonical catalog should be used.

Verify that the chosen API supports the actual requirements for:

* React rendering and locale changes.

* Interpolation of runtime values.

* Pluralization and grammatical context.

* Missing-key handling.

* Accessible names and descriptions.

* Dynamic notifications and errors.

* Nested components and portals.

* Locale-aware formatting.

* Appropriate fallback behavior.

Do not assemble complete translated sentences from English-specific fragments.

Prefer complete translation messages with named parameters for genuine runtime values.

Keep interpolation values distinct from translated resource content, and follow the chosen localization library's security guidance for untrusted values and rich text.

Avoid translating machine-readable identifiers, technical diagnostics, file paths, codec identifiers, project data, or internal error codes unless a product requirement explicitly calls for a user-facing representation.

### 6. Preserve language preference and runtime consistency

Verify the current precedence rules for locale selection.

Unless the established application contract says otherwise, use:

1. An explicit user selection.

2. A valid persisted preference.

3. A valid system or browser language preference on first launch.

4. English as the final fallback.

Never allow repeated automatic language detection to override the user's explicit preference.

A language change should update relevant mounted and newly mounted UI without requiring an unnecessary restart.

Check relevant tooltips, dialogs, notifications, accessibility labels, native menus, and dynamic text.

Verify that changing languages does not alter the meaning or persisted state of the user's project, timeline, playback, or rendering operations.

Handle missing, invalid, and unsupported stored locale identifiers safely.

### 7. Apply correct locale-sensitive formatting

Use locale-aware mechanisms for values such as dates, times, numbers, file sizes, percentages, and counts where applicable.

Respect each locale's pluralization rules and formatting conventions.

Do not assume that English plural behavior, number separators, or date formats are valid for every language.

Keep locale-dependent presentation separate from underlying application data.

For NLE functionality, preserve the semantic distinction between:

* Display timecode.

* Absolute media timestamps.

* Frame indices.

* Rational time values.

* Audio sample positions.

* Human-readable durations.

Do not alter canonical time values or machine-readable media data just because a display locale changes.

Use appropriate locale formatting for descriptions without changing the underlying media semantics.

### 8. Check internationalized UI and accessibility

Inspect how translated text affects the actual UI.

Where relevant, verify:

* Long and short translations.

* Text wrapping and truncation.

* Tooltip positioning and overflow.

* Dialog size and scrolling.

* Keyboard navigation and focus.

* Accessible names and descriptions.

* Screen-reader announcements.

* CJK font fallback and glyph coverage.

* Responsive layouts and window sizes.

* Text direction and layout assumptions.

Prefer logical CSS properties and reusable layout patterns.

Prepare locale metadata for text direction where appropriate, but do not claim right-to-left support unless it is implemented and verified.

Respect platform conventions for shortcut descriptions, while preserving the actual shortcut behavior.

### 9. Localize the native Tauri boundary

Inspect native menus, Rust-originated messages, Tauri commands, plugins, and other relevant native integrations.

Identify a single source of truth or an explicitly defined translation contract between the frontend and backend.

Avoid duplicating the same message in independent TypeScript and Rust catalogs without consistency checks.

Use structured error categories or stable error identifiers where practical, allowing the frontend to display appropriate localized messages.

Verify initial native menu labels at startup and subsequent language changes where the product supports live updates.

Account for the case where the native menu is initialized before the frontend has restored the user's preferred locale.

Keep system-owned UI distinct from application-owned UI.

When a feature has different OS-specific behavior, use the Tauri cross-platform engineering skill.

### 10. Enforce catalog quality

Use the repository's existing tooling or add justified deterministic checks.

Where applicable, validate:

* Locale identifiers and supported-language declarations.

* Catalog structure and canonical key parity.

* Required translations and explicit exceptions.

* Interpolation variable consistency.

* Plural resource completeness.

* Missing-key diagnostics.

* Unexpected untranslated content.

* Translation imports and resource loading.

* Native menu message consistency.

* Availability of every supported locale in the language selector.

Do not interpret matching key counts as proof that all translations are correct.

Do not flag every occurrence of English as a defect. Proper nouns, product names, technical terms, code identifiers, and intentionally shared terminology require appropriate treatment.

Do not add blanket exclusions that hide genuine untranslated strings.

Ensure that an incorrect catalog causes the relevant validation command to fail.

Integrate the canonical localization validation command into CI.

### 11. Test realistic localization behavior

Choose the lowest-level test that proves each individual requirement, then add UI or native integration tests where necessary.

Unit and catalog tests should validate catalog integrity, fallback, preference precedence, interpolation, pluralization, and locale formatting.

Component tests should verify rendered text, accessibility attributes, and behavior after language changes.

Playwright tests should exercise representative visible workflows, including language selection, newly opened dialogs, tooltips where practical, notifications, accessibility labels, and locale persistence.

Use explicit test adapters for native APIs that are unavailable in the browser. Do not treat mocked native commands as proof of actual Tauri integration.

Use the repository's supported Tauri desktop-testing strategy when real native behavior must be verified.

Test every supported locale structurally, and run representative application-level localization smoke tests across all declared locales. Use risk-based selection for more expensive end-to-end scenarios.

Test text layout with longer translations and relevant writing systems.

For any observed localization defect, add a regression test whenever practical.

### 12. Distinguish structural quality from linguistic quality

Automated tests can establish catalog consistency and application behavior, but they cannot independently guarantee natural, contextually accurate translation.

Identify unreviewed translations when that status can be established.

Use consistent product terminology for timeline operations, transitions, effects, tracks, media, playback, and rendering.

Document the linguistic review process and prioritize ambiguous, technically significant, or safety-relevant messages.

Do not describe machine-generated translations as professionally validated without supporting evidence.

Do not silently rewrite all translations during an unrelated feature change.

### 13. Perform the post-implementation audit

After implementation, independently search for relevant omissions.

Ask:

* Did the change introduce hard-coded text?

* Were tooltip and accessibility strings covered?

* Do dynamic and asynchronous messages use the active locale?

* Are pluralization and interpolation correct?

* Does the native boundary remain consistent?

* Can long translations break the layout?

* Does the selected language survive application restart?

* Are unsupported locales and missing keys handled correctly?

* Have relevant Playwright and integration tests been run?

* Are other supported locales or platforms affected?

* Are there any unverified outcomes that were incorrectly treated as complete?

Add relevant tests for uncovered scenarios.

Do not claim exhaustive coverage merely because every catalog key exists.

### 14. Report evidence

For a non-trivial localization task, report:

* The affected localization architecture and UI surfaces.

* The supported locales and any relevant fallback behavior.

* Missing, malformed, or intentionally exempt catalog entries.

* New or updated automated tests.

* Executed commands and their actual results.

* Playwright workflows tested.

* Native desktop checks completed, if applicable.

* Known linguistic, visual, platform, or runtime gaps.

Distinguish catalog structure, application runtime behavior, desktop integration, and linguistic quality.

Never claim that a check passed unless it was actually executed and its result verified.

## Rules

* Always inspect existing localization patterns before changing them.

* Always use the canonical localization API for new application-owned user-facing text.

* Always consider tooltips, dynamic messages, errors, menus, and accessibility strings where relevant.

* Always preserve project data and NLE semantics when changing presentation language.

* Always consider locale-specific grammar, pluralization, formatting, and text expansion.

* Always add meaningful regression coverage for discovered localization defects where practical.

* Never use key parity as proof of translation quality.

* Never use DOM translation as a substitute for understanding React rendering and state.

* Never allow an explicit user preference to be silently overridden by automatic detection.

* Never claim native, visual, or linguistic verification that has not occurred.

* Never replace the existing localization architecture wholesale without evidence and a migration strategy.

* Prefer incremental, testable improvements with clear compatibility guarantees.

## Expected Output

For implementation tasks, follow the repository's normal engineering completion report.

For localization work, explicitly identify localization coverage, test evidence, and unverified behavior.

For review tasks, report concrete defects and missing verification with file and line references where available.

For exploratory questions, explain the relevant architecture and trade-offs without modifying files unless requested.

More agent context in AIEraDev/Clypra

19 other files this repository gives its agents.