You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: locale-specification.md
+62-3Lines changed: 62 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -687,7 +687,66 @@ The recommended implementation sequence, prioritized by impact:
687
687
688
688
---
689
689
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
691
750
692
751
| Locale | IETF tag | File suffix | HTML `lang`| Directory name |
0 commit comments