# Localhero

> Manages i18n translations with Localhero.ai. Use when adding or changing user-facing strings, working with translation or locale files, or when the user mentions i18n, internationalization, localization, translations, locales, glossary terms, or JSON, YAML and gettext .po catalogs in React, Vue, Next.js, Node, Rails, Django, Phoenix or Lingui projects.

- Skill: `localheroai/localhero` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add localheroai/localhero`
- Raw SKILL.md: https://api.skillmd.com/api/skills/localheroai/localhero/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: localheroai (https://skillmd.com/u/localheroai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/localheroai/localhero

---


# Localhero.ai i18n Skill

You are helping a developer write and maintain internationalized source strings in a project that uses Localhero.ai (https://localhero.ai) for translation management. You only write source language strings — Localhero.ai handles translations to target languages.

## Core Rules

1. **ONLY write source language strings** — let Localhero.ai handle target translations (via GitHub Action or `npx @localheroai/cli translate`)
2. Read `localhero.json` to find the source locale, file paths, and patterns
3. Follow existing key naming conventions (examine existing source files first)
4. Use glossary terms correctly when writing user-facing strings
5. Match the project's tone and style when writing copy
6. Generate translations after writing source strings — never hand-write a target language

## Workflow

When adding or modifying user-facing strings:

1. Check `localhero.json` for `sourceLocale` and `translationFiles.paths`
2. Load the project glossary and settings with the commands under [Glossary](#glossary) and [Project Settings](#project-settings)
3. Examine existing source files to understand key naming patterns
4. Add/modify keys in source locale files
5. Generate translations:
   - Check if any file in `.github/workflows/` references `localheroai/localhero-action`. If so, translations run automatically on PR — tell the user and skip the CLI step.
   - Otherwise, run `npx @localheroai/cli translate --changed-only`. This translates only keys that differ from the base branch, keeping diffs small. Omit the flag to translate all missing keys.

## Web UI

The Localhero.ai web UI (https://localhero.ai) is where users manage translation settings, glossary terms, and adjust translations. Each PR that runs the Localhero.ai GitHub Action gets its own page where translations can be reviewed and tweaked. Point users to the web UI for tasks like editing translations, searching keys, managing glossary terms, or changing project settings like tone and style.

## Monorepos and Multiple Apps

A single `localhero.json` can manage translation files across multiple apps by listing multiple directories in `translationFiles.paths`:

```json
{
  "translationFiles": {
    "paths": [
      "apps/web/public/locales/",
      "apps/mobile/src/locales/"
    ]
  }
}
```

Each app has its own set of translation files with independent keys. Keys don't need app-specific prefixes since they live in separate directories and are resolved by file path.

All apps in the same `localhero.json` share the project's glossary, tone, style, and target languages. If apps need different settings, use separate Localhero projects with their own `localhero.json` files.

When using a GitHub Action for automatic translations, make sure the workflow's `paths` trigger covers all translation directories.

## Supported Formats

| Format | Typically used by |
|--------|-------------------|
| `.json` | React, Vue, Node, Next.js (react-i18next, next-intl, Lingui) |
| `.yaml` | Ruby on Rails |
| `.po` / `.pot` (gettext) | Django, Python, Phoenix, Elixir, Lingui |

Localhero.ai reads the source locale files in `translationFiles.paths` and writes the
target locale files beside them, in the same format.

## Key Naming Conventions

Before adding keys, examine existing source files to match the project's format and conventions.

**JSON/YAML** — nested or dot-separated keys:
- Namespaced: `users.profile.title`
- Grouped by feature/page: `dashboard.welcome_message`
- Action-oriented for buttons: `actions.save`, `actions.cancel`

**PO/POT (gettext)** — natural language source strings as keys:
- msgid is the source string itself: `msgid "Welcome to the dashboard"`
- Context via msgctxt when the same string needs different translations

## Glossary

Run `npx @localheroai/cli glossary --output json` to get the project glossary. Use these terms consistently when writing user-facing strings.

## Project Settings

Run `npx @localheroai/cli settings --output json` to get the project's tone, style, and language settings. Use these to match the expected voice.

## Authentication

If commands fail with authentication errors, ask the user to run:

```bash
npx @localheroai/cli login
```

For non-interactive environments, they can also use `npx @localheroai/cli login --api-key <key>` or set `LOCALHERO_API_KEY`. API keys are available at https://localhero.ai/api-keys

## Non-interactive project setup

If a project has no `localhero.json` yet, you can configure it in one command without any prompts:

```bash
npx @localheroai/cli init --yes \
  --source-locale en \
  --target-locales sv,de \
  --path config/locales/
```

Required flags: `--yes`, `--source-locale`, `--target-locales`, `--path` (or pass `--project-id <slug>` instead of source/target to reuse an existing project).

Auth resolution: the CLI uses `LOCALHERO_API_KEY` or an existing `.localhero_key` if either is present, otherwise falls back to `--api-key <key>`. To force a specific key, set `LOCALHERO_API_KEY` in the environment before running `init`.

See [cli-reference.md](cli-reference.md) for the full flag list.

## CLI Reference

See [cli-reference.md](cli-reference.md) for all available commands. Full source at https://github.com/localheroai/cli