Skip to content

Commit 2199555

Browse files
brunoborgesCopilot
andcommitted
Add translation governance: English source of truth, agent + human workflow
- Add Section 12: Translation Governance - English is canonical source; translations are derived - Technical content synced by coding agents - Non-technical prose welcomes human/community contributions - l10n-sync commit SHA tracking for freshness - CONTRIBUTING.md template for translation guidelines - Renumber sections 13-15 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 5138ee9 commit 2199555

1 file changed

Lines changed: 62 additions & 3 deletions

File tree

locale-specification.md

Lines changed: 62 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -687,7 +687,66 @@ The recommended implementation sequence, prioritized by impact:
687687

688688
---
689689

690-
## 12. File Naming & Locale Codes
690+
## 12. Translation Governance
691+
692+
### English is the source of truth
693+
694+
All content is authored in English first. English files are the **canonical source** — translated files are derived from them. When English content changes, translated content must be updated to match.
695+
696+
### Content classification
697+
698+
Content in these repos falls into two categories with different translation workflows:
699+
700+
| Type | Examples | Translation approach |
701+
|------|----------|---------------------|
702+
| **Technical** | Code blocks, CLI commands, file paths, configuration snippets, step-by-step instructions that reference IDE features, API names, tool names | **Coding agents** should handle these translations. They can reliably propagate structural changes, update code references, and keep technical accuracy consistent across locales. |
703+
| **Non-technical** | Prose descriptions, workshop introductions, motivational text, "What You'll Learn" summaries, cultural references in bingo questions, hero subtitles | **Human contributions welcome.** Native speakers produce more natural, engaging prose than machine translation. Community pull requests improving these sections should be encouraged. |
704+
705+
### Keeping translations in sync
706+
707+
When English content is updated:
708+
709+
1. **Use coding agents** (e.g., GitHub Copilot coding agent, Copilot CLI) to propagate changes to translated files. Agents should:
710+
- Identify which English files changed (via diff against the previous version).
711+
- Apply the corresponding structural changes to each locale's files.
712+
- Translate new or modified technical content (steps, commands, UI references).
713+
- Flag non-technical prose changes for human review rather than auto-translating them.
714+
715+
2. **Open a PR per locale** with the agent-generated updates. Mark non-technical prose sections with `<!-- NEEDS_HUMAN_REVIEW -->` comments so reviewers know which parts would benefit from a native speaker's touch.
716+
717+
3. **Label PRs** with `localization` and the locale code (e.g., `l10n:pt_BR`, `l10n:es`) for easy filtering.
718+
719+
### Welcoming community contributions
720+
721+
Each repo's `CONTRIBUTING.md` should include a section like:
722+
723+
```markdown
724+
## 🌐 Translations
725+
726+
We welcome contributions to improve translations! If you're a native speaker
727+
of Portuguese (BR) or Spanish and notice awkward phrasing, cultural mismatches,
728+
or opportunities to make the content more natural, please open a PR.
729+
730+
**Guidelines:**
731+
- English is the source of truth — do not add content that doesn't exist in English.
732+
- Focus on improving prose quality, not restructuring content.
733+
- Do not translate code blocks, file paths, CLI commands, or tool/feature names.
734+
- Keep the same markdown structure and formatting as the English original.
735+
```
736+
737+
### Translation freshness tracking
738+
739+
To track whether translated files are up to date, each translated file should include a comment at the top referencing the English source commit it was last synced with:
740+
741+
```markdown
742+
<!-- l10n-sync: english-commit-sha="abc1234" -->
743+
```
744+
745+
This allows coding agents to quickly determine which files are stale by comparing the recorded SHA against the latest English file's history.
746+
747+
---
748+
749+
## 13. File Naming & Locale Codes
691750

692751
| Locale | IETF tag | File suffix | HTML `lang` | Directory name |
693752
|--------|----------|-------------|-------------|----------------|
@@ -699,7 +758,7 @@ Use underscores (`pt_BR`) in file/directory names for cross-platform compatibili
699758

700759
---
701760

702-
## 13. Cross-Repo Consistency Rules
761+
## 14. Cross-Repo Consistency Rules
703762

704763
Since all five repos share the same locale picker UI and the four workshop repos share identical content structure:
705764

@@ -712,7 +771,7 @@ Since all five repos share the same locale picker UI and the four workshop repos
712771

713772
---
714773

715-
## 14. Quality Checklist
774+
## 15. Quality Checklist
716775

717776
Before shipping a locale:
718777

0 commit comments

Comments
 (0)