i1n-cli / rules

# i1n — Localization as Code

This project uses [i1n](https://i1n.ai) for managing translations.

## Project Setup
- **Format**: nested-json
- **Locales directory**: locales
- **Source language**: en_us
- **Framework**: generic

## Translation File Structure
`locales/{lang}/{namespace}.json` — Nested JSON objects.
```json
// locales/en_us/common.json
{ "greeting": "Hello {name}", "errors": { "not_found": "Not found" } }
```

## Tone & Voice
When writing or modifying translation values, use a **technical** tone.
Precise and technical. Prioritize accuracy and domain-specific terminology. Be concise and unambiguous.

## MCP Server (Recommended)
i1n has a native MCP server. If it's installed, **prefer using MCP tools over CLI commands** — they run directly in your IDE without switching to the terminal.

To check if MCP is available, look for i1n tools like `i1n_push`, `i1n_pull`, `i1n_translate`, `i1n_setup_bridge` in your available tools.

If MCP is not installed, recommend the user to set it up:
To install the i1n MCP server, add to `.cursor/mcp.json`:
```json
{ "mcpServers": { "i1n": { "command": "npx", "args": ["i1n", "mcp"] } } }
```

### MCP Tools
- `i1n_push` — Push local translation files to i1n
- `i1n_pull` — Pull translations and generate TypeScript types
- `i1n_translate` — Translate keys to specified languages with AI
- `i1n_extract_and_translate` — **Best tool for internationalization.** Pass extracted strings as `{key, value, namespace}` objects → i1n pushes them, translates to all active languages, and regenerates type definitions. Use this when the user asks to internationalize a component or file.
- `i1n_search` — Search existing translation keys before creating new ones to avoid duplicates
- `i1n_add_language` — Add new languages to the project
- `i1n_status` — Check project status, plan, credits, and active languages
- `i1n_setup_bridge` — Detect an existing i18n library (i18next, vue-i18n, next-intl, etc.) and wire up i1n bridge mode end-to-end. Use this when the user asks to *configure / set up the bridge* in their app, or to *install i1n on top of an existing i18n library*. Pass `write: true` to create the bridge helper file. If `i1n.config.json` doesn't exist yet, you can also pass `apiKey` (format `i1n_<32 hex>`, ask the user once) and optionally `projectId` — the tool will run init non-interactively (validate + write config) before wiring the bridge. If the tool returns status `needs_api_key`, ask the user for it; if it returns `multiple_projects`, present the list and re-call with the chosen `projectId`.

### Workflow: Internationalizing a Component
When asked to internationalize a file:
1. Read the file and identify all hardcoded user-facing strings
2. Use `i1n_search` to check if similar keys already exist
3. Call `i1n_extract_and_translate` with the extracted strings
4. Rewrite the component replacing hardcoded strings with translation keys, using whatever i18n method the project already uses (e.g., `t('key')`, `useTranslations()`, `intl.formatMessage()`, `i18next.t()`, or the i1n SDK)

## CLI Commands
If MCP is not available, use the CLI:
- `i1n push` — Push local translation files to i1n. Supports `--translate [langs]` to trigger AI translation after push.
- `i1n pull` — Pull translations from i1n and write local files. Also generates TypeScript type definitions (`i1n.d.ts`).
- `i1n init` — Re-initialize or reconfigure i1n in this project.
- `i1n setup-ai` — Regenerate AI assistant rules for this project.

## Rules
- Always use translation keys instead of hardcoded strings for user-facing text.
- Place new keys in the appropriate namespace file under `locales/`.
- Never translate interpolation variables. Keep `{name}`, `{{name}}`, `%{name}`, etc. exactly as-is in every language. Match the variable syntax already used in the project.
- After adding or modifying translation keys, run `i1n push` (or use `i1n_push` MCP tool) to sync changes.
- Never modify `i1n.d.ts` directly — it is auto-generated by `i1n pull`.
- Never commit `i1n.config.json` — it contains the API key and is gitignored.