| name | website-i18n |
| description | Envilder website internationalization workflow. Use when adding, editing, or reviewing translated strings, creating localized pages, or verifying i18n completeness. Covers the full lifecycle from type definition to locale files. |
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
| What | Where |
|---|
| Translation types | src/website/src/i18n/types.ts |
| Locale files | src/website/src/i18n/{en,ca,es}.ts (one per locale) |
| i18n utilities | src/website/src/i18n/utils.ts |
| Astro i18n config | src/website/astro.config.mjs → i18n.locales |
| Pages (default locale) | src/website/src/pages/*.astro |
| Pages (other locales) | src/website/src/pages/<locale>/*.astro |
Adding New Translations: 4-Step Workflow
1. Define the type
Add the new key structure in src/website/src/i18n/types.ts:
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: Catalanes.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, --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:
- TypeScript compilation catches missing keys (
tsc --noEmit or dev server)
- Navigate to each locale in dev server to verify text renders
- Optionally delegate to
@i18n Reviewer for linguistic quality check
