diff --git a/.agents/skills/docs-sync/SKILL.md b/.agents/skills/docs-sync/SKILL.md index a1ea33c..0f2bc0b 100644 --- a/.agents/skills/docs-sync/SKILL.md +++ b/.agents/skills/docs-sync/SKILL.md @@ -41,6 +41,7 @@ The following files are the documentation targets. All must be kept in sync: | `docs/letsmesh.md` | LetsMesh packet decoding: normalization, channel keys, message handling | | `docs/hosting/nginx-proxy-manager.md` | Nginx Proxy Manager admin authentication setup guide | | `docs/seeding.md` | Seed data: node tags and members YAML format, directory structure, import process | +| `docs/i18n.md` | Translation reference: all i18n keys, variable interpolation, translation tips | | `.env.example` | Example environment file with comments and defaults | | `SCHEMAS.md` | Event JSON schemas and database column mappings | diff --git a/.agents/skills/docs-sync/references/documentation-checklist.md b/.agents/skills/docs-sync/references/documentation-checklist.md index fcd8dc2..d019664 100644 --- a/.agents/skills/docs-sync/references/documentation-checklist.md +++ b/.agents/skills/docs-sync/references/documentation-checklist.md @@ -58,6 +58,7 @@ For each variable in each table: - [ ] Seed data directory structure (`node_tags.yaml`, `members.yaml`) documented in `docs/seeding.md` - [ ] Custom content directory structure (`pages/`, `media/`) documented - [ ] Translation files location (`src/meshcore_hub/web/static/locales/`) documented +- [ ] Translation reference guide (`docs/i18n.md`) linked from README and AGENTS.md - [ ] No references to removed files (PLAN.md, TASKS.md) ## 2. AGENTS.md @@ -175,6 +176,22 @@ docs/seeding.md documents the seed data format and import process for node tags - [ ] Member field table fields match `MemberCreate` Pydantic schema - [ ] Example seed files referenced in `example/seed/` exist +## 3e. docs/i18n.md + +### Translation Reference Guide + +docs/i18n.md is a comprehensive reference for translators. Verify: + +- [ ] Translation file location path (`src/meshcore_hub/web/static/locales/`) is correct +- [ ] Each translation section key matches a top-level key in `en.json` +- [ ] Entity keys (`entities.*`) match current `en.json` values +- [ ] Common pattern keys (`common.*`) match current `en.json` values +- [ ] Composite pattern examples produce correct output with current entity names +- [ ] Variable interpolation syntax (`{{variable}}`) matches actual usage in `en.json` +- [ ] Admin section keys match current admin page translations +- [ ] No stale translation keys documented (removed from `en.json`) +- [ ] Translation tips are accurate for current i18n system + ## 4. .env.example ### Section Structure diff --git a/AGENTS.md b/AGENTS.md index 191ac8b..ae66776 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,6 +41,7 @@ MeshCore Hub is a Python 3.14+ monorepo for managing and orchestrating MeshCore - [docs/letsmesh.md](docs/letsmesh.md) - LetsMesh packet decoding details - [docs/hosting/nginx-proxy-manager.md](docs/hosting/nginx-proxy-manager.md) - Nginx Proxy Manager admin setup - [docs/seeding.md](docs/seeding.md) - Seed data format and import guide +- [docs/i18n.md](docs/i18n.md) - Translation reference guide ## Technology Stack @@ -342,6 +343,7 @@ meshcore-hub/ │ ├── images/ # Screenshots and images │ ├── hosting/ # Reverse proxy hosting guides │ │ └── nginx-proxy-manager.md +│ ├── i18n.md # Translation reference guide │ ├── letsmesh.md # LetsMesh packet decoding details │ ├── seeding.md # Seed data format and import guide │ └── upgrading.md # Upgrade guide for breaking changes @@ -489,7 +491,7 @@ The web dashboard supports internationalization via JSON translation files. The **Key files:** - `en.json` - English translations (reference implementation) -- `languages.md` - Comprehensive translation reference guide for translators +- [docs/i18n.md](docs/i18n.md) - Comprehensive translation reference guide for translators **Using translations in JavaScript:** @@ -523,7 +525,7 @@ const emptyMsg = t('common.no_entity_found', { entity: t('entities.nodes').toLow - Group related keys by section (e.g., `admin_members.*`, `admin_node_tags.*`) - Use `{{variable}}` syntax for dynamic content -2. **Update `languages.md`** with: +2. **Update `docs/i18n.md`** with: - Key name, English value, and usage context - Variable descriptions if using interpolation - Notes about HTML content or special formatting @@ -544,7 +546,7 @@ const emptyMsg = t('common.no_entity_found', { entity: t('entities.nodes').toLow - **Compose with entities:** Reference `entities.*` keys in patterns rather than hardcoding entity names - **Preserve variables:** Keep `{{variable}}` placeholders unchanged when translating - **Test composition:** Verify patterns work with all entity types (singular/plural, lowercase/uppercase) -- **Document context:** Always update `languages.md` so translators understand usage +- **Document context:** Always update `docs/i18n.md` so translators understand usage **Example - adding a new entity and patterns:** @@ -558,7 +560,7 @@ const emptyMsg = t('common.no_entity_found', { entity: t('entities.nodes').toLow t('common.add_entity', { entity: t('entities.sensor') }) // "Add Sensor" t('common.no_entity_found', { entity: t('entities.sensors').toLowerCase() }) // "No sensors found" -// 3. Update languages.md with context +// 3. Update docs/i18n.md with context // 4. Add test to test_i18n.py ``` @@ -569,7 +571,7 @@ The i18n system (`src/meshcore_hub/common/i18n.py`) loads translations on startu - Falls back to English for missing keys - Returns the key itself if translation not found -For full translation guidelines, see `src/meshcore_hub/web/static/locales/languages.md`. +For full translation guidelines, see [docs/i18n.md](docs/i18n.md). ### Adding a New Database Model diff --git a/README.md b/README.md index 228b16c..247ef71 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Python 3.14+ platform for managing and orchestrating MeshCore mesh networks. > [!IMPORTANT] > **Help Translate MeshCore Hub** 🌍 > -> We need volunteers to translate the web dashboard! Currently only English is available. Check out the [Translation Guide](src/meshcore_hub/web/static/locales/languages.md) to contribute a language pack. Partial translations welcome! +> We need volunteers to translate the web dashboard! Currently only English is available. Check out the [Translation Guide](docs/i18n.md) to contribute a language pack. Partial translations welcome! ## Overview @@ -623,7 +623,7 @@ meshcore-hub/ │ ├── templates/ # Jinja2 templates (SPA shell) │ └── static/ │ ├── js/spa/ # SPA frontend (ES modules, lit-html) -│ └── locales/ # Translation files (en.json, languages.md) +│ └── locales/ # Translation files (en.json) ├── tests/ # Test suite ├── alembic/ # Database migrations ├── etc/ # Configuration files (MQTT, Prometheus, Alertmanager) @@ -651,6 +651,7 @@ meshcore-hub/ │ ├── images/ # Screenshots and images │ ├── hosting/ # Reverse proxy hosting guides │ │ └── nginx-proxy-manager.md +│ ├── i18n.md # Translation reference guide │ ├── letsmesh.md # LetsMesh packet decoding details │ ├── seeding.md # Seed data format and import guide │ └── upgrading.md # Upgrade guide for breaking changes @@ -665,6 +666,7 @@ meshcore-hub/ - [docs/letsmesh.md](docs/letsmesh.md) - LetsMesh packet decoding details - [docs/seeding.md](docs/seeding.md) - Seed data format and import guide - [docs/hosting/nginx-proxy-manager.md](docs/hosting/nginx-proxy-manager.md) - Nginx Proxy Manager admin setup +- [docs/i18n.md](docs/i18n.md) - Translation reference guide - [AGENTS.md](AGENTS.md) - Guidelines for AI coding assistants ## Contributing diff --git a/src/meshcore_hub/web/static/locales/languages.md b/docs/i18n.md similarity index 100% rename from src/meshcore_hub/web/static/locales/languages.md rename to docs/i18n.md