Skip to content

Commit 41f8dba

Browse files
iliakaniliakan
committed
readme
1 parent 80956ed commit 41f8dba

File tree

1 file changed

+157
-22
lines changed

1 file changed

+157
-22
lines changed

‎README.md

+157-22
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,174 @@
1-
# The Modern JavaScript Tutorial
1+
# The Modern JavaScript Tutorial in Finnish
22

3-
This repository hosts the English content of the Modern JavaScript Tutorial, published in [https://javascript.info](https://javascript.info).
3+
This repository hosts the translation of <https://javascript.info> in Finnish.
44

5-
## Translations
65

7-
We'd like to make the tutorial available in many languages. Please help us to translate.
6+
**That's how you can contribute:**
87

9-
See <https://javascript.info/translate> for the details.
8+
- See the [Finnish Translate Progress](https://github.com/javascript-tutorial/fi.javascript.info/issues/1) issue.
9+
- Choose an unchecked article you'd like to translate.
10+
- Add a comment with the article title to the issue, e.g. `An Introduction to JavaScript`.
11+
- Our bot will mark it in the issue, for everyone to know that you're translating it.
12+
- Your comment should contain only the title.
13+
- Fork the repository, translate and send a PR when done.
14+
- PR title should match article title, the bot will write it's number into the issue.
1015

11-
## Contributions
16+
Please kindly allow maintainers to review and merge or request changes in your translation.
17+
18+
If maintainers do not respond, or if you'd like to become a maintainer, write us at the [main repo](https://github.com/javascript-tutorial/en.javascript.info/issues/new).
19+
20+
**Let others know what you're translating, in message boards or chats in your language. Invite them to join!**
1221

13-
We'd also like to collaborate on the tutorial with other people.
22+
🎉 Thank you!
1423

15-
Something's wrong? A topic is missing? Explain it to people, add as PR 👏
24+
Your name and the contribution size will appear in the "About project" page when the translation gets published.
1625

17-
**You can edit the text in any editor.** The tutorial uses enhanced "markdown" format, easy to grasp. And if you want to see how it looks on-site, there's a server to run the tutorial locally at <https://github.com/javascript-tutorial/server>.
18-
19-
The list of contributors is available at <https://javascript.info/about#contributors>.
26+
P.S. The full list of languages can be found at <https://javascript.info/translate>.
2027

2128
## Structure
2229

23-
Every chapter, article or a task has its folder.
30+
Every chapter, an article or a task resides in its own folder.
31+
32+
The folder is named `N-url`, where `N` – is the number for sorting (articles are ordered), and `url` is the URL-slug on the site.
33+
34+
The folder has one of files:
35+
36+
- `index.md` for a section,
37+
- `article.md` for an article,
38+
- `task.md` for a task formulation (+`solution.md` with the solution text if any).
39+
40+
A file starts with the `# Title Header`, and then the text in Markdown-like format, editable in a simple text editor.
41+
42+
Additional resources and examples for the article or the task, are also in the same folder.
43+
44+
## Translation Tips
45+
46+
Please keep line breaks and paragraphs "as is": don't add newlines and don't remove existing ones. Makes it easy to merge future changes from the English version into the translation.
47+
48+
If you see that the English version can be improved – great, please send a PR to it.
49+
50+
### Terms
51+
52+
- Some specification terms are not to be translated, e.g. "Function Declaration" can be left "as is".
53+
- For other terms like `resolved promise`, `slash`, `regexp`, and so on - look for a glossary, hopefully there's one for your language already. If not, look for translations in manuals, such as [MDN](https://developer.mozilla.org/en-US/).
54+
55+
56+
### Terms with meaning
57+
58+
In English many terms have an obvious meaning. For a person who doesn't understand English, there's no such meaning.
59+
60+
Please keep that in mind, sometimes explanations or additional translations are needed, e.g.
61+
62+
```md
63+
`ReadableStream` allows to read data chunk-by-chunk.
64+
```
65+
66+
The class name `ReadableStream` has an obvious meaning for those who understand English.
67+
68+
Some people who read translations may not know English so well. So we can add a translation of `ReadableStream` in parentheses, like this (Spanish below):
69+
70+
```md
71+
`ReadableStream` ("flujo legible") permite leer datos fragmento por fragmento.
72+
```
73+
74+
### Text in Code Blocks
75+
76+
- Translate comments.
77+
- Translate user-messages and example strings.
78+
- Don't translate variables, classes, identifiers.
79+
- Ensure that the code works after the translation :)
80+
81+
Example:
82+
83+
```js
84+
// Example
85+
const text = "Hello, world";
86+
document.querySelector('.hello').innerHTML = text;
87+
```
88+
89+
✅ DO (translate comment):
90+
91+
```js
92+
// Ejemplo
93+
const text = 'Hola mundo';
94+
document.querySelector('.hello').innerHTML = text;
95+
```
96+
97+
❌ DON'T (translate class):
98+
99+
```js
100+
// Ejemplo
101+
const text = 'Hola mundo';
102+
// ".hello" is a class
103+
// DO NOT TRANSLATE
104+
document.querySelector('.hola').innerHTML = text;
105+
```
106+
107+
Please note, that sometimes code is followed by pictures, and if you translate text `Hello` -> `Hola` in the code, you need to translate text in picturess as well.
108+
109+
In that case it's probably easier not to translate such text. See more about translating images later.
110+
111+
112+
### External Links
113+
114+
If an external link is to Wikipedia, e.g. `https://en.wikipedia.org/wiki/JavaScript`, and a version of that article exists in your language that is of decent quality, link to that version instead.
115+
116+
Example:
117+
118+
```md
119+
[JavaScript](https://en.wikipedia.org/wiki/JavaScript) is a programming language.
120+
```
121+
122+
✅ OK (en -> es):
123+
124+
```md
125+
[JavaScript](https://es.wikipedia.org/wiki/JavaScript) es un lenguaje de programación.
126+
```
127+
128+
For links to MDN, a partially translated version is ok.
129+
130+
If a linked article has no translated version, leave the link "as is".
131+
132+
### Metadata
133+
134+
Some files, usually tasks, have YAML metadata at the top, delimited by `---`:
135+
136+
```md
137+
importance: 5
138+
139+
---
140+
...
141+
```
142+
143+
Please don't translate "importance" (and other top metadata).
144+
145+
### Anchors
146+
147+
Some headers have `[#anchor]` at the end, e.g.
148+
149+
```md
150+
## Spread operator [#spread-operator]
151+
```
152+
153+
Please don't translate or remove the `[#...]` part, it's for URL anchors.
154+
155+
156+
### Images
24157

25-
The folder is named like `N-url`, where `N` is a number for the sorting purposes and `url` is the URL part with title of the material.
158+
Most illustrations use SVG format, the text in there can be replaced with a translated variant.
26159

27-
The type of the material is defined by the file inside the folder:
160+
The translated text is in `images.yml` file in the tutorial root.
28161

29-
- `index.md` stands for a chapter
30-
- `article.md` stands for an article
31-
- `task.md` stands for a task (solution must be provided in `solution.md` file as well)
162+
The file format is YAML:
163+
```yaml
164+
image.svg: # image file
165+
"hello world": # English phrase
166+
text: "Hola mundo" # translation
167+
position: "centre" # "center" or "right", if needed to center or right-align the translation
168+
```
32169
33-
Each of these files starts from the `# Main header`.
170+
## Running locally
34171
35-
It's very easy to add something new.
172+
You can run the tutorial server locally to see how the translation looks.
36173
37-
---
38-
♥
39-
Ilya Kantor @iliakan
174+
The server and install instructions are at <https://github.com/javascript-tutorial/server>.

0 commit comments

Comments
 (0)