docs: update copilot-instructions.md with i18n and enterprise category

- Add enterprise to categories list and display names table
- Document translations/ directory structure and locales.properties
- Add full Internationalization (i18n) section referencing specs/i18n/i18n-spec.md
- Document UI strings, content translation schema, and fallback behavior
- Update generated files section with locale-specific output paths
- Expand manually maintained files and project structure

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: brunoborges

.github/copilot-instructions.md

@@ -18,33 +18,48 @@ content/streams/stream-tolist.json
 ...
 ```
 
-**Categories:** `language`, `collections`, `strings`, `streams`, `concurrency`, `io`, `errors`, `datetime`, `security`, `tooling`
+**Categories:** `language`, `collections`, `strings`, `streams`, `concurrency`, `io`, `errors`, `datetime`, `security`, `tooling`, `enterprise`
 
 ### Generated Files (DO NOT EDIT)
 
 The following are **generated by `html-generators/generate.java`** and must not be edited directly:
 
-- `site/index.html` — homepage with preview cards (generated from `templates/index.html`)
-- `site/language/*.html`, `site/collections/*.html`, etc. — detail pages
-- `site/data/snippets.json` — aggregated search index
+- `site/index.html` — English homepage with preview cards (generated from `templates/index.html`)
+- `site/language/*.html`, `site/collections/*.html`, etc. — English detail pages
+- `site/data/snippets.json` — English aggregated search index
+- `site/{locale}/index.html` — localized homepage (e.g., `site/es/index.html`)
+- `site/{locale}/language/*.html`, etc. — localized detail pages
+- `site/{locale}/data/snippets.json` — localized search index
 
-Run `jbang html-generators/generate.java` to rebuild all generated files from the JSON sources.
+Run `jbang html-generators/generate.java` to rebuild all generated files from the JSON sources and translations.
 
 ### Manually Maintained Files
 
-- `site/app.js` — client-side search, filtering, code highlighting
+- `site/app.js` — client-side search, filtering, code highlighting, locale detection
 - `site/styles.css` — all styling
-- `templates/slug-template.html` — HTML template with `{{placeholder}}` tokens used by the generator
-- `templates/index.html` — homepage template with `{{tipCards}}` and `{{snippetCount}}` placeholders
+- `templates/slug-template.html` — HTML template with `{{placeholder}}` tokens (content + UI strings) used by the generator
+- `templates/index.html` — homepage template with `{{tipCards}}`, `{{snippetCount}}`, and UI string placeholders
 - `templates/index-card.html` — preview card template for the homepage grid
+- `html-generators/categories.properties` — category ID → display name mapping
+- `html-generators/locales.properties` — supported locales registry (locale=Display name)
+- `translations/strings/{locale}.yaml` — UI strings per locale (labels, nav, footer, etc.)
+- `translations/content/{locale}/` — translated pattern JSON files (partial, translatable fields only)
 
 ### Project Structure
 
 ```
-content/            # Source JSON files (one per pattern, organized by category)
+content/            # English content JSON files (source of truth, one per pattern)
+translations/       # All i18n artifacts
+  strings/          # UI strings per locale (en.yaml, es.yaml, pt-BR.yaml)
+  content/          # Translated pattern files per locale (partial, translatable fields only)
+    es/             # Spanish translations (mirrors content/ folder structure)
+    pt-BR/          # Brazilian Portuguese translations
 site/               # Deployable site (static assets + generated HTML)
-templates/          # HTML templates for detail pages
-html-generators/    # Build scripts and pre-built JAR
+  es/               # Generated Spanish pages
+  pt-BR/            # Generated Portuguese pages
+templates/          # HTML templates with {{…}} tokens for content + UI strings
+html-generators/    # Build scripts, categories.properties, locales.properties
+specs/              # Feature specifications (e.g., i18n-spec.md)
 ```
 
 ## JSON Snippet Schema
@@ -101,6 +116,8 @@ Each `content/category/slug.json` file has this structure:
 
 ## Category Display Names
 
+Categories and their display names are defined in `html-generators/categories.properties`:
+
 | ID | Display |
 |----|---------|
 | `language` | Language |
@@ -113,12 +130,59 @@ Each `content/category/slug.json` file has this structure:
 | `datetime` | Date/Time |
 | `security` | Security |
 | `tooling` | Tooling |
+| `enterprise` | Enterprise |
 
 ## Adding a New Pattern
 
 1. Create `content/category/new-slug.json` with all required fields
 2. Update `prev`/`next` in the adjacent patterns' JSON files
 3. Run `jbang html-generators/generate.java`
+4. (Optional) Create translated content files under `translations/content/{locale}/category/new-slug.json` with only translatable fields — or let the AI translation workflow handle it
+
+## Internationalization (i18n)
+
+The site supports multiple languages. See `specs/i18n/i18n-spec.md` for the full specification.
+
+### Key Concepts
+
+- **UI strings:** Hard-coded template text (labels, nav, footer) is extracted into `translations/strings/{locale}.yaml`. Templates use `{{dotted.key}}` tokens (e.g., `{{nav.allPatterns}}`, `{{sections.codeComparison}}`). Missing keys fall back to the English value with a build-time warning.
+- **Content translations:** Translated pattern files under `translations/content/{locale}/` contain **only** translatable fields (`title`, `summary`, `explanation`, `oldApproach`, `modernApproach`, `whyModernWins`, `support.description`). All other fields (`oldCode`, `modernCode`, `slug`, `id`, `prev`, `next`, `related`, `docs`, etc.) are always taken from the English source.
+- **Locale registry:** `html-generators/locales.properties` lists supported locales (format: `locale=Display name`). The first entry is the default.
+- **English is a first-class locale:** All locales — including English — go through the same build pipeline.
+- **Fallback:** If a pattern has no translation file for a locale, the English content is used and an "untranslated" banner is shown.
+
+### Supported Locales
+
+Defined in `html-generators/locales.properties`:
+
+| Locale | Display Name |
+|--------|-------------|
+| `en` | English |
+| `es` | Español |
+| `pt-BR` | Português (Brasil) |
+
+### Content Translation File Example
+
+Translation files contain **only** translatable fields — no structural data:
+
+```json
+// translations/content/pt-BR/language/type-inference-with-var.json
+{
+  "title": "Inferência de tipo com var",
+  "oldApproach": "Tipos explícitos",
+  "modernApproach": "Palavra-chave var",
+  "summary": "Use var para deixar o compilador inferir o tipo local.",
+  "explanation": "...",
+  "whyModernWins": [
+    { "icon": "⚡", "title": "Menos ruído", "desc": "..." },
+    { "icon": "👁",  "title": "Mais legível", "desc": "..." },
+    { "icon": "🔒", "title": "Seguro", "desc": "..." }
+  ],
+  "support": {
+    "description": "Amplamente disponível desde o JDK 10 (março de 2018)"
+  }
+}
+```
 
 ## Local Development