I18n localization workflow

Skill Chagai33/my-agent-skills/i18n-localization-workflow

My personal collection of custom AI Agent Skills for Claude Code. Contains production-grade architectural patterns and workflows for React, Firebase, Tailwind CSS, and Zustand.

Install

npx -y skills add Chagai33/my-agent-skills --skill i18n-localization-workflow

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Trigger this skill when adding new text to UI components, adding new languages, or when doing bulk translation updates.

SKILL.md

3.1 KB, as published. Nobody here has run it

i18n Localization Workflow

This project uses react-i18next for translations, supporting languages like Hebrew (he), English (en), and Spanish (es). Because the app is heavily localized and supports RTL/LTR, strict rules apply to how text is added and managed.

When to use this skill

Adding new UI components that contain text.
Adding or modifying messages, labels, or tooltips.
Auditing the project for missing translations or hardcoded text.
Performing bulk updates to the .json language files.

❌ What NOT to do

Strictly NO Regex for Source Code Parsing: Never use regular expressions (Regex) to extract translation keys (t('...')) or find hardcoded text (e.g., matching Hebrew characters). They are fragile and cause silent failures. Always use an AST parser (like ts-morph or typescript) for robust static analysis.
DO NOT hardcode user-facing text. Never write <div>Hello World</div>. Always use <div>{t('common.greeting')}</div>.
DO NOT use dynamic keys that cannot be statically analyzed. Avoid t("status_" + status). Prefer mapping statuses to explicit keys, or sending the exact key. This breaks static analysis scripts.
DO NOT manually edit multiple .json files for large structural changes. If you are adding a whole new section (e.g., a new page), use the update_locales.cjs script to patch all languages simultaneously using deepMerge.
DO NOT ignore directional layout (RTL/LTR). When creating UI, remember that properties like ml-4 might break in RTL. Use logical properties like ms-4 (margin-start) or space-x-4 rtl:space-x-reverse when relevant.

Golden Examples

1. Standard Component Usage

A typical React component extracting translations via the useTranslation hook.

templates/component-usage.tsx

2. Checking for Missing Translations & Hardcoded Hebrew

Before deploying, it's crucial to verify that all t('keys') exist in he.json and that no Hebrew text is hardcoded in .tsx files.

scripts/check_translations.js

3. Bulk Updating Locales

When adding new features with many strings across multiple languages, use a script to inject them structurally into all locales/*.json files at once.

scripts/update_locales.cjs

Key Concepts

Fallback Language: Hebrew (he.json) is the absolute source of truth and fallback language. If a key is missing in English, the app will show Hebrew.
Namespace: We use a single namespace structure (often under a root object or direct). Nested objects (like eventPage.category.addItem) are the standard way to group keys.
Automated Verification: The Node.js scripts in the root directory (check_translations.js) use Regular Expressions to parse .tsx files physically, looking for t('...') calls and Hebrew unicode characters [\u0590-\u05FF]. Always ensure code plays nicely with these parsers.