Skip to content

Commit 0d54794

Browse files
sethvincentsethvincent
authored
Merge pull request workshopper#191 from claudiopro/master
Adds a howto to localize the workshopper to new languages
2 parents 8211ace + 0dca662 commit 0d54794

1 file changed

Lines changed: 115 additions & 0 deletions

File tree

‎LOCALIZING.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Localization HOWTO
2+
3+
In computing, localization is the process of adapting software to different languages, regional differences, cultural preferences, and technical requirements of a target audience.
4+
5+
This guide explains how to contribute a new localization to this workshopper. If you are an international user and would like to bring Nodeschool workshops to a broader audience, please consider contributing a localization! It is simple, fun, and enables more people to learn and practice.
6+
7+
## Add the language option
8+
9+
In the `index.js` file, the workshopper is instantiated with a list of supported translations. In order to add a new language, add its code to the array:
10+
11+
```js
12+
const workshopper = require('workshopper-adventure')({
13+
appDir: __dirname
14+
, languages: ['en', 'ja', 'zh-cn']
15+
, header: require('workshopper-adventure/default/header')
16+
, footer: require('./lib/footer.js')
17+
});
18+
```
19+
20+
If you want to add a new language, e.g. Spanish, add an entry `'es'` to the array:
21+
22+
```js
23+
, languages: ['en', 'es', 'ja', 'zh-cn']
24+
```
25+
26+
## Menu
27+
28+
The menu of the workshopper greets the user with a list of problem names. The strings for these names are contained in the top level `menu.json` file. Translations of problem names should be placed in a JSON file inside the `i18n` folder named with the language code, e.g. `es.json`. Use an existing translation file as reference, ensuring it's up to date with the contents of `menu.json`.
29+
30+
```json
31+
{
32+
"exercise": {
33+
"INTRODUCTION": "INTRODUCCIÓN"
34+
, "FIRST PROBLEM": "PRIMER PROBLEMA"
35+
, "SECOND PROBLEM": "SEGUNDO PROBLEMA"
36+
, "LAST PROBLEM": "ÚLTIMO PROBLEMA"
37+
}
38+
}
39+
```
40+
41+
## Footer
42+
43+
Workshoppers usually display a footer beneath the problem description, providing the user with help or additional information to make their way through. The footer is a [Markdown](https://en.wikipedia.org/wiki/Markdown) file located inside the `i18n/footer` directory, named after the language code, e.g. `ja.md`.
44+
45+
In order to add a localized footer for Spanish, create a `es.md` file inside the `i18n/footer` directory, containing the translation of the English file `en.md`.
46+
47+
## Troubleshooting tips
48+
49+
Similarly, workshoppers display troubleshooting tips when the user submits a wrong solution for the exercise. Tips are contained in a [Markdown](https://en.wikipedia.org/wiki/Markdown) file located inside the `i18n` directory, named after the language code, e.g. `troubleshooting-ja.md`.
50+
51+
In order to add translated troubleshooting tips for Spanish, create a `troubleshooting_es.md` file inside the `i18n` directory, containing the translation of the English file `troubleshooting.md`.
52+
53+
## Problems and solutions
54+
55+
The text of each problem and the message printed when the user solves it can be localized by adding [Markdown](https://en.wikipedia.org/wiki/Markdown) files with a well defined name inside the problem directory, which is a subdirectory of the `problems` directory. Consider this structure:
56+
57+
```
58+
+-- problems
59+
| +-- problem-1
60+
| | +-- index.js
61+
| | +-- problem.md
62+
| | +-- problem_ja.md
63+
| | +-- problem_zh-cn.md
64+
| | +-- solution.md
65+
| | +-- solution_ja.md
66+
| | `-- solution_zh-cn.md
67+
| +-- problem-2
68+
| | +-- index.js
69+
| | +-- problem.md
70+
| | +-- problem_ja.md
71+
| | +-- problem_zh-cn.md
72+
| | +-- solution.md
73+
| | +-- solution_ja.md
74+
| | `-- solution_zh-cn.md
75+
: :
76+
```
77+
78+
As you can see, translation file names are in the format `problem_xx.md` and `solution_xx.md` where the `xx` suffix is the language code.
79+
80+
In order to add the Spanish localization, we must add new `problem_es.md` and `solution_es.md` files inside each problem directory as follows:
81+
82+
```
83+
+-- problems
84+
| +-- problem-1
85+
| | +-- index.js
86+
| | +-- problem.md
87+
| | +-- problem_es.md
88+
| | +-- problem_ja.md
89+
| | +-- problem_zh-cn.md
90+
| | +-- solution.md
91+
| | +-- solution_es.md
92+
| | +-- solution_ja.md
93+
| | `-- solution_zh-cn.md
94+
| +-- problem-2
95+
| | +-- index.js
96+
| | +-- problem.md
97+
| | +-- problem_es.md
98+
| | +-- problem_ja.md
99+
| | +-- problem_zh-cn.md
100+
| | +-- solution.md
101+
| | +-- solution_es.md
102+
| | +-- solution_ja.md
103+
| | `-- solution_zh-cn.md
104+
: :
105+
```
106+
107+
This is probably the most complex and time consuming task of localizing a workshopper, as problems often interleave paragraphs of text, code snippets and suggestions.
108+
109+
Please remember to use welcoming and inclusive language. The [Contributor Covenant](http://contributor-covenant.org/) offers guidelines if you're unsure.
110+
111+
## Testing
112+
113+
In order to test a translation, launch the workshopper and choose the desired language selecting the menu option `CHOOSE LANGUAGE`. If you don't see the language you contributed listed in the options, chances are you didn't save your updates to the list of languages in the `index.js`.
114+
115+
Once you're satisfied with the results, commit your changes and push to your repo, then submit a PR to the main workshopper repo!

0 commit comments

Comments
 (0)