add-locale

name	add-locale
description	Add a new translation locale to the Polar frontend. Walks through registering the locale, generating translations, wiring the generated file into the i18n package, and updating the public-facing docs. Expects the target locale's ISO 639-1 alpha-2 code (optionally with a BCP-47 region suffix, e.g. `pt-PT`).
user-invocable	true
allowed-tools	Read Edit Write Bash Grep Glob

Add a new translation locale

This skill adds a new locale to the Polar frontend i18n package (clients/packages/i18n) and the corresponding public docs. Each step produces its own commit so the PR reads cleanly.

Ask the user for the locale if they haven't provided one. You need:

• ${isoAlpha2} — the locale code used as the filename and config key (e.g. ko, ja, pt-PT). This is the value appended to SUPPORTED_LOCALES verbatim.
• ${localeName} — the human-readable name used in LOCALE_NAMES (e.g. Korean (South Korea), Japanese). Follow the style of the existing entries in clients/packages/i18n/src/config.ts.

Throughout this doc, ${isoAlpha2} is substituted literally into filenames, branch names, commit messages, and identifiers.

Step 1: Sync main

git checkout main
git pull --ff-only

Bail out if the working tree isn't clean — ask the user before stashing or discarding anything.

Step 2: Create the branch

git checkout -b add-locale-${isoAlpha2}

Step 3: Register the locale

Edit clients/packages/i18n/src/config.ts:

1. Append '${isoAlpha2}' to the SUPPORTED_LOCALES tuple (keep the as const).
2. Add a ${isoAlpha2}: '${localeName}' entry to LOCALE_NAMES. Quote the key if it contains a dash (e.g. 'pt-PT').

Commit:

git add clients/packages/i18n/src/config.ts
git commit -m "Register ${isoAlpha2}"

Step 4: Generate the translation file

cd clients/packages/i18n
pnpm translate

This produces clients/packages/i18n/src/locales/${isoAlpha2}.ts. Confirm the file exists and has content before committing.

git add clients/packages/i18n/src/locales/${isoAlpha2}.ts
git commit -m "Generate ${isoAlpha2}"

Step 5: Wire the locale into the i18n entrypoint

Edit clients/packages/i18n/src/index.ts:

1. Add an import near the other locale imports:

   import ${importName} from './locales/${isoAlpha2}'
   

   For plain alpha-2 codes use the code itself (import ko from './locales/ko'). For hyphenated codes drop the dash and camelCase it to keep a valid identifier (import ptPT from './locales/pt-PT').
2. Add the locale to the translations LocalesRecord object. Use the bare key when it's a valid identifier (ko,) or a quoted key when it's hyphenated ('pt-PT': ptPT,).

Commit:

git add clients/packages/i18n/src/index.ts
git commit -m "Enable ${isoAlpha2}"

Step 6: Update the public docs

Edit docs/features/checkout/localization.mdx:

• Add - ${localeName} (${isoAlpha2}) to the "Supported languages" list.
• Remove the locale from the "coming soon" list if it was listed there.

Commit:

git add docs/features/checkout/localization.mdx
git commit -m "Update localization docs"

Step 7: Hand back to the user

Summarize the four commits created on add-locale-${isoAlpha2} and leave the branch for the user to push and open a PR. Do not push or open a PR unless asked.