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
Enhance translations.md with comprehensive translation guide
Expanded the translations document to include detailed instructions for translating the Open Source Guides, including a table of contents, translation workflow, best practices, and quality assurance guidelines.
Copy file name to clipboardExpand all lines: docs/translations.md
+183-8Lines changed: 183 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,15 @@
1
1
# Translations
2
2
3
-
Thanks for your interest in helping to translate the guides!
3
+
Thanks for your interest in helping to translate the guides! This document provides comprehensive instructions for translating the Open Source Guides into other languages.
4
+
5
+
## Table of Contents
6
+
7
+
-[Starting a translation](#starting-a-translation)
8
+
-[Translation workflow](#translation-workflow)
9
+
-[Best practices for translators](#best-practices-for-translators)
10
+
-[Quality assurance](#quality-assurance)
11
+
-[Updating a translation](#updating-a-translation)
12
+
-[Getting help](#getting-help)
4
13
5
14
## Starting a translation
6
15
@@ -9,16 +18,138 @@ Before you start working on a translation, look through the [open pull requests]
9
18
If there's not, then today is your day to lead this effort! Here's how to start:
10
19
11
20
1.[Fork this repository](https://github.com/github/opensource.guide/fork)
12
-
1.[Set up your environment](../CONTRIBUTING.md#setting-up-your-environment)
13
-
1. Create a new branch for your translation work e.g. `es`.
14
-
1. Copy `_data/locales/en.yml` to your target language file e.g. `_data/locales/es.yml` and translate all the strings.
15
-
1. Create a new directory in `_articles/` for your language e.g. `_articles/es/`, copy each guide from `_articles/` into that folder and translate the content in each guide, except for the field names in the front matter between the `---`s at the top of each file, e.g., `title:` should remain unchanged.
16
-
1. Copy `index.html` to your target language index file e.g. `[_articles/es/index.html](https://github.com/github/opensource.guide/blob/HEAD/_articles/es/index.html)` and update the `lang:` and add the `permalink:` fields. Example: `lang: es` and `permalink: /es/`. All other fields' values must remain unchanged.
17
-
1. Run `script/test` and make sure there are no failures with your translation files. Note that you may need to fix broken links.
18
-
1. Send a pull request. (You may send a pull request before all steps above are complete: e.g., you may want to ask for help with translations, or getting tests to pass. However, your pull request will not be merged until all steps above are complete.)
21
+
2.[Set up your environment](../CONTRIBUTING.md#setting-up-your-environment)
22
+
3. Create a new branch for your translation work e.g. `es`.
23
+
4. Copy `_data/locales/en.yml` to your target language file e.g. `_data/locales/es.yml` and translate all the strings.
24
+
5. Create a new directory in `_articles/` for your language e.g. `_articles/es/`, copy each guide from `_articles/` into that folder and translate the content in each guide, except for the field names in the front matter between the `---`s at the top of each file, e.g., `title:` should remain unchanged.
25
+
6. Copy `index.html` to your target language index file e.g. `_articles/es/index.html` and update the `lang:` and add the `permalink:` fields. Example: `lang: es` and `permalink: /es/`. All other fields' values must remain unchanged.
26
+
7. Run `script/test` and make sure there are no failures with your translation files. Note that you may need to fix broken links.
27
+
8. Send a pull request. (You may send a pull request before all steps above are complete: e.g., you may want to ask for help with translations, or getting tests to pass. However, your pull request will not be merged until all steps above are complete.)
28
+
29
+
### Working with other translators
19
30
20
31
Completing an initial translation of the whole site is a fairly large task. One way to break that task up is to work with other translators through pull requests on your fork. Example: [pull requests on fork for German translation](https://github.com/katrinleinweber/opensource.guide/pulls?q=is%3Apr+is%3Aclosed) and corresponding [initial pull request for German translation](https://github.com/github/opensource.guide/pull/577) on this repository. You can also [add collaborators to your fork](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/inviting-collaborators-to-a-personal-repository) if you'd like to invite other translators to commit directly to your fork and share responsibility for merging pull requests.
21
32
33
+
## Translation workflow
34
+
35
+
### Phase 1: Setup (Day 1)
36
+
- Fork the repository
37
+
- Set up your local development environment
38
+
- Create a translation branch
39
+
- Announce your translation effort by opening a draft pull request
40
+
41
+
### Phase 2: UI Strings (Days 1-2)
42
+
- Translate `_data/locales/en.yml`
43
+
- This file contains all the user interface strings (navigation, buttons, etc.)
44
+
- Test locally to see your translations in the UI
45
+
46
+
### Phase 3: Content Translation (Days 3-14)
47
+
- Translate articles one by one
48
+
- Start with shorter articles to build momentum
49
+
- Maintain consistency in terminology across all articles
50
+
- Keep the front matter fields unchanged
51
+
52
+
### Phase 4: Review and Polish (Days 15-17)
53
+
- Review all translations for consistency
54
+
- Check that technical terms are used appropriately
55
+
- Run tests to catch broken links
56
+
- Ask for feedback from native speakers
57
+
58
+
### Phase 5: Final submission (Day 18+)
59
+
- Address any feedback
60
+
- Ensure all tests pass
61
+
- Mark your pull request as ready for review
62
+
63
+
## Best practices for translators
64
+
65
+
### Language and tone
66
+
- Maintain the friendly, welcoming tone of the original content
67
+
- Use inclusive language appropriate for your target audience
68
+
- Adapt cultural references when necessary, but keep the core message
69
+
70
+
### Technical terminology
71
+
- Use established translations for technical terms when they exist in your language
72
+
- Keep English terms in backticks (e.g., `pull request`) if no good translation exists
73
+
- Create a glossary for your language to ensure consistency
74
+
- Consider what terms your community commonly uses (e.g., do they use "fork" or translate it?)
75
+
76
+
### Formatting
77
+
- Preserve all markdown formatting
78
+
- Keep links intact - only translate the link text, not the URL
79
+
- Maintain the same heading structure
80
+
- Don't translate code examples, file paths, or command-line examples
81
+
- Keep HTML comments unchanged
82
+
83
+
### Front matter
84
+
**Do NOT translate these fields:**
85
+
-`layout:`
86
+
-`class:`
87
+
-`order:`
88
+
89
+
**DO translate these fields:**
90
+
-`title:`
91
+
-`description:`
92
+
93
+
**New fields to add:**
94
+
-`lang:` (your language code, e.g., `es`, `fr`, `de`)
95
+
-`permalink:` (e.g., `/es/` for the index page)
96
+
97
+
### Examples
98
+
99
+
Good translation example:
100
+
```yaml
101
+
---
102
+
lang: es
103
+
title: Cómo Contribuir al Código Abierto
104
+
description: ¿Quieres contribuir al código abierto? Una guía para hacer contribuciones, tanto para principiantes como para veteranos.
105
+
class: contribute
106
+
order: 1
107
+
---
108
+
```
109
+
110
+
Bad translation example (don't do this):
111
+
```yaml
112
+
---
113
+
idioma: es # Wrong: don't translate field names
114
+
título: Cómo Contribuir
115
+
class: contribuir # Wrong: don't translate class
116
+
order: uno # Wrong: keep numbers as numbers
117
+
---
118
+
```
119
+
120
+
## Quality assurance
121
+
122
+
### Self-review checklist
123
+
Before submitting your translation, check that:
124
+
125
+
-[ ] All UI strings in `_data/locales/[lang].yml` are translated
126
+
-[ ] All article files are translated
127
+
-[ ] Index page is created with correct `lang` and `permalink`
128
+
-[ ] Front matter fields are correctly handled (some translated, some not)
129
+
-[ ] All links work correctly
130
+
-[ ] Technical terms are used consistently
131
+
-[ ] Tests pass locally (`script/test`)
132
+
-[ ] No English text remains (except code examples, file paths, technical terms)
133
+
-[ ] Markdown formatting is preserved
134
+
-[ ] Tone matches the original guides
135
+
136
+
### Testing
137
+
Run these commands to test your translation:
138
+
139
+
```bash
140
+
# Test for broken links and formatting issues
141
+
script/test
142
+
143
+
# Run the site locally to preview your translation
144
+
script/server
145
+
# Then visit http://localhost:4000/[your-lang]/ in your browser
146
+
```
147
+
148
+
### Getting feedback
149
+
- Ask other native speakers to review your translation
150
+
- Share the preview link from your fork's GitHub Pages (if enabled)
151
+
- Respond to review comments promptly
152
+
22
153
## Updating a translation
23
154
24
155
### Corrections
@@ -36,3 +167,47 @@ Add the updated text in English to all translations to implicitly solicit pull r
36
167
### New articles
37
168
38
169
We do not plan on ever adding any new articles.
170
+
171
+
## Getting help
172
+
173
+
### Resources for translators
174
+
- Check existing translations to see how others handled similar content
0 commit comments