conventions-i18n

$npx mdskill add stella/stella/conventions-i18n

Standardize international string translations for Stella applications.

  • Ensures consistent, idiomatic translations across all supported languages.
  • Depends on use-intl runtime and typegen for type declarations.
  • Prioritizes reusable generic keys over feature-specific naming patterns.
  • Requires manual updates to JSON files before running type generation.

SKILL.md

.github/skills/conventions-i18nView on GitHub ↗
---
name: conventions-i18n
description: 'Internationalization conventions for Stella. Apply when adding or modifying user-facing strings.'
---

# i18n Conventions

Internationalization conventions for Stella. Apply when adding or
modifying user-facing strings.

## Stack

`use-intl` for runtime.

## Supported Languages

en is the source language. Check `apps/web/src/i18n/langs/` for
the current list of target languages (add translations to every
`.json` file found there).

## Translation Flow

1. Add or modify keys in
   `apps/web/src/i18n/langs/en.json`.
2. Add corresponding translations to **all target language files**
   found in `apps/web/src/i18n/langs/` (every `.json` file
   except `en.json`). Write natural, idiomatic translations;
   avoid literal/robotic phrasing.
3. Run `i18n-typegen src/i18n/langs` (from `apps/web`) to
   regenerate type declarations (also runs automatically
   before `bun run typecheck`).

## Key Naming

**Prefer generic, reusable keys over feature-specific ones.**
Before adding any new i18n key, search `en.json` for an existing
key with the same or similar wording (e.g., `common.filter`,
`common.sort`, `common.columns`). Reuse `common.*` or shared
namespace keys instead of creating feature-scoped duplicates
like `billing.expenses.deleteExpense`. Feature-specific keys
are only justified when the wording truly differs from the
generic version (e.g., a confirmation message that mentions
the resource by name).

Key naming, pluralization, and style rules are documented
in `apps/web/src/i18n/TERMINOLOGY.md`.

More from stella/stella

SkillDescription
case-briefingExtract structural components of judicial decisions across legal traditions (common law, civil law, and international tribunals).
click-aroundAutonomous browser-based QA and UX smoke test. Starts the dev server, takes control of Chrome, walks through user stories for a feature area, monitors the console, and produces a structured report on what works, what breaks, and what feels wrong.
contract-analysisStructural decomposition and analysis of contracts across legal traditions (common law, civil law, CISG/UNIDROIT).
conventions-dbApply when writing or modifying database schema, queries, or migrations.
conventions-scaleApply when making architectural decisions, designing new endpoints, or adding database tables.
conventions-securityApply when writing code that touches auth, data access, file handling, or external APIs. Stella handles privileged legal data (attorney-client privilege, litigation holds, personal data).
conventions-testingApply when writing or reviewing tests.
conventions-uxApply when building or modifying user-facing UI components.
data-protectionGDPR compliance analysis covering lawful basis assessment, privacy notices, processor agreements, and breach response.
devLaunch the local dev environment using the project''s dev-runner. The runner handles env symlinks, Docker services, port allocation, health checks, and browser opening automatically.