macalbert/envilder/website-i18n

Website i18n

Every user-visible string on the Envilder website MUST go through the i18n system. Never hardcode text in components.

When to Use

• Adding new user-visible text to any component or page
• Creating a new page (must create locale variants)
• Reviewing PRs that add/change website content
• Checking i18n completeness after content changes

File Locations

Adding New Translations: 4-Step Workflow

1. Define the type

Add the new key structure in src/website/src/i18n/types.ts:

// In the Translations interface
section: {
  title: string;
  description: string;
};

2. Add strings to every locale file

Update all locale files in src/website/src/i18n/:

• en.ts: English (source)
• ca.ts: Catalan
• es.ts: Spanish

TypeScript will error if any locale is missing a key defined in types.ts.

3. Use in component

Access translations via the useTranslations helper:

---
import { useTranslations } from '../i18n/utils';
const { lang = 'en' } = Astro.props;
const t = useTranslations(lang);
---
<h2>{t.section.title}</h2>
<p>{t.section.description}</p>

4. Create localized pages

For new pages:

• Default locale: src/website/src/pages/new-page.astro
• Other locales: src/website/src/pages/<locale>/new-page.astro

Check astro.config.mjs → i18n.locales to discover all active locales.

Terms That MUST NOT Be Translated

Product names, CLI flags, code tokens, and acronyms stay in English:

envilder, AWS SSM, Azure Key Vault, GitHub Action, envilder.json, .env, --map, --envfile, envilder exec, --provider, --push, CI/CD, IAM, RBAC, CLI, API, JSON, YAML, Node.js, pnpm, npx

Constraints

• Never hardcode user-visible text: always use i18n keys
• Never hardcode version numbers: use __SDK_*_VERSION__ / __APP_VERSION__

globals from astro.config.mjs

• All 3 locales must be updated simultaneously (TypeScript catches mismatches)
• Preserve existing key structure: add new keys, don't rename existing ones

without updating all references

Verification

After adding translations:

1. TypeScript compilation catches missing keys (tsc --noEmit or dev server)
2. Navigate to each locale in dev server to verify text renders
3. Optionally delegate to @i18n Reviewer for linguistic quality check