Skip to content

Commit 5424172

Browse files
committed
Add suggestions and workflow example
In the process of translating _LBFtCL_ to spanish we realized about some differences in our understanding of translation process. Those differences generated some more work to some of us. I think that some exemplification through the `WORKFLOW EXAMPLE` added, can clarify some ideas behind the translation process and avoid further extra work. Also, in the process of translating and reviewing I found some simple ideas that made the process easier, or that could have made the process easier. Those were added under the `FINAL SUGGESTIONS` section.
1 parent 4a44502 commit 5424172

File tree

1 file changed

+67
-0
lines changed

1 file changed

+67
-0
lines changed

TRANSLATING.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,4 +45,71 @@ Thank you for your interest in translating Learning Bitcoin from the Command Lin
4545
* It is our hope that translations will stay up to day with new releases, particularly major and minor releases, which are likely to include new content and updates. Currently, these only occur ever few years
4646
* If you have decided to stop updating a translation, please let us know in an Issue, so that we can let the community know that we are looking for a new translator to continue updating a translation.
4747

48+
### WORKFLOW EXAMPLE
49+
50+
Chapter 3 has 7 subsections: 3.0, 3.1, 3.2, 3.3, Interlude 3.3, 3.4 and 3.5.
51+
Suppose you want to translate it to french.
52+
53+
One approach to its translation would be to create a branch `french-3` from
54+
`french-translation` branch (created in the previous step). Then create a
55+
translation file for the 3.0 subsection. When you think that chapter 3.0 is
56+
ready for review you commit your changes and continue with the next file,
57+
subsection 3.1. Repeat the same process for this file and all the following.
58+
After this, your branch `french-3` will diverge from the base branch
59+
(`french-translation` in this case) by 7 different commits, one for each
60+
subsection, plus some more commits if you forgot to make some changes or need
61+
to correct others. At this point you are ready to push your changes to your
62+
fork and open a pull request to the original repository.
63+
64+
In the review process you will discuss some decisions with your reviewer and
65+
introduce new changes in the form of commits if you have to change some parts
66+
of your modifications. Don't forget to commit those changes in meaningful
67+
chunks and push them to your fork. After polishing your changes, your reviewer
68+
will accept your changes and it will request the merge of those changes on the
69+
`french-translation` branch. Note that you can also push your changes and
70+
create your pull request after your first commit. This will allow the reviewer
71+
to start reviewing before you finish all chapter translation.
72+
73+
You can track the state of the translation of that particular chapter in the
74+
body of the pull request, with the following template:
75+
76+
---
77+
78+
This pull request creates the <translated_language> version of the chapter
79+
<chapter_number> of Learning-Bitcoin-from-the-Command-Line.
80+
81+
Things to check:
82+
- Respect filenames and chapter names from translated [README](local/path/to/README).
83+
- Correct translation.
84+
- Term consistency: review ["translation memory"](local/path/to/file) file.
85+
- Good punctuation.
86+
- Correct linking.
87+
- Nice formatting.
88+
89+
| Sub chapter | Translated | Reviewed | Done |
90+
| ------------- | :--------------: | :--------------: | :--------------: |
91+
| _0_ | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> |
92+
| _1_ | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> |
93+
| _2_ | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> |
94+
| _3_ | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> |
95+
| _etc_ | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> | <ul><li> [ ] </li></ul> |
96+
97+
-----
98+
99+
### FINAL SUGGESTIONS:
100+
- _Keep lines under 80 characters_. Markdown parser will format them right
101+
(double check that) and the review process will be easier.
102+
- _Translate `README.md` file first_ and use it as reference for the translation
103+
of all the following chapter names, filenames and link names. The README
104+
represents the state of the master branch at the moment of begin the
105+
translation process. It will be consulted by all translators to know how to
106+
translate file and chapter names. Try to reach an agreement with the other
107+
translators about those names before writing any chapter and keep further
108+
changes of this file to minimum.
109+
- _Create a "translation memory" file_ with special words that could have
110+
multiple translations under the same contexts and the translation chosen for
111+
them. Good candidates to be in this list would be domain specific words,
112+
like: multisig, input, output, script, timelock, locktime, hash, etc.
113+
114+
48115
Again, thank you!

0 commit comments

Comments
 (0)