This document attempts to describe the process that translators should follow. This will be an evolving discussion and I will gladly accept pull requests from translators or others who have experience in such matters in an effort to improve the translation process.
The following people have taken on the responsibility for translation into various languages. If you have are interested in helping with the translation in one of these languages, please contact the associated coordinator. If the language you would like to translate the book into is not mentioned here, then contact me if you are interested in volunteering to coordinate the translation into that language:
- Spanish - Susana López
- Chinese - Lionel Belmon Discussion
- Italian - Marco Romanoni
- Portuguese - Julião Cicero
I've tried to make the translation process as simple as possible for translators by trying to do as much of the "up front" work on my end.
When you check out the Git repository, you'll find a directory called
text/locale. In there, you'll find directories that
correspond to all the different languages for which translations are
being done (e.g., es=Spanish, cn=Chinese). Simply go into the
directory corresponding to the language you interested in translating
and then into the LC_MESSAGES directory inside there and look for
the .po files contained in those directories. These files contain
the text to be translated.
The file contains lots of entries corresponding to different passages of text. A typical passage might look like this:
#: ../../source/front/dedication.rst:11
msgid ""
"This book started as a Kickstarter project. The idea of writing a book and "
"making it freely available, under a Creative Commons license, was largely "
"inspired by the writings of Cory Doctorow and Lawrence Lessig. Their "
"message of sharing resonated very strongly with me. I'm not interested in "
"capitalizing on my knowledge of Modelica, I want to share it with others so "
"they can experience the same joy I do in exploring this subject. Happily, "
"this Kickstarter project was successfully funded on December 4th, 2012 and "
"my odyssey to create an entire Creative Commons licensed book began. If "
"circumstances had been different, this book would probably be dedicated to "
"Cory Doctorow and Lawrence Lessig for inspiring me to take on this project."
msgstr ""
#: ../../source/front/dedication.rst:23
To translate this text, what is required is to add text below the
msgstr line that is a translated version of the English language
text above. For example, the code above might be translated (e.g.,
into French) as:
#: ../../source/front/dedication.rst:11
msgid ""
"This book started as a Kickstarter project. The idea of writing a book and "
"making it freely available, under a Creative Commons license, was largely "
"inspired by the writings of Cory Doctorow and Lawrence Lessig. Their "
"message of sharing resonated very strongly with me. I'm not interested in "
"capitalizing on my knowledge of Modelica, I want to share it with others so "
"they can experience the same joy I do in exploring this subject. Happily, "
"this Kickstarter project was successfully funded on December 4th, 2012 and "
"my odyssey to create an entire Creative Commons licensed book began. If "
"circumstances had been different, this book would probably be dedicated to "
"Cory Doctorow and Lawrence Lessig for inspiring me to take on this project."
msgstr ""
"Ce livre a commencé comme un projet Kickstarter. L'idée d'écrire un livre et "
"rendant disponible gratuitement, sous une licence Creative Commons, était en grande partie "
"inspiré par les écrits de Cory Doctorow et Lawrence Lessig. Leur "
"un message de partage résonné très fort avec moi. Je ne suis pas intéressé par "
"capitaliser sur ma connaissance de Modelica, je veux le partager avec d'autres pour "
"ils peuvent éprouver la même joie que je fais dans l'exploration de ce sujet. Heureusement, "
"ce projet Kickstarter a été financé avec succès le 4 Décembre 2012 et "
"mon odyssée à créer un ensemble de Creative Commons livre licence a commencé. Si "
"circonstances avaient été différentes, ce livre serait probablement dédié à "
"Cory Doctorow et Lawrence Lessig de m'inspirer de prendre sur ce projet."
Note the addition of the lines following the line with the msgstr directive on it.
In some cases, I may fix a typo or adjust the text after something has
been translated. So I want to take a moment to explain what happens
in that case. If a section of the original text has changed, the
translation will be commented out using both a # character and a
~, as follows:
#: ../../source/front/dedication.rst:11
#~ msgid ""
#~ "This book started as a Kickstarter project. The idea of writing a book and "
#~ "making it freely available, under a Creative Commons license, was largely "
#~ "inspired by the writings of Cory Doctorow and Lawrence Lessig. Their "
#~ "message of sharing resonated very strongly with me. I'm not interested in "
#~ "capitalizing on my knowledge of Modelica, I want to share it with others so "
#~ "they can experience the same joy I do in exploring this subject. Happily, "
#~ "this Kickstarter project was successfully funded on December 4th, 2012 and "
#~ "my odyssey to create an entire Creative Commons licensed book began. If "
#~ "circumstances had been different, this book would probably be dedicated to "
#~ "Cory Doctorow and Lawrence Lessig for inspiring me to take on this project."
#~ msgstr ""
#~ "Ce livre a commencé comme un projet Kickstarter. L'idée d'écrire un livre et "
#~ "rendant disponible gratuitement, sous une licence Creative Commons, était en grande partie "
#~ "inspiré par les écrits de Cory Doctorow et Lawrence Lessig. Leur "
#~ "un message de partage résonné très fort avec moi. Je ne suis pas intéressé par "
#~ "capitaliser sur ma connaissance de Modelica, je veux le partager avec d'autres pour "
#~ "ils peuvent éprouver la même joie que je fais dans l'exploration de ce sujet. Heureusement, "
#~ "ce projet Kickstarter a été financé avec succès le 4 Décembre 2012 et "
#~ "mon odyssée à créer un ensemble de Creative Commons livre licence a commencé. Si "
#~ "circonstances avaient été différentes, ce livre serait probablement dédié à "
#~ "Cory Doctorow et Lawrence Lessig de m'inspirer de prendre sur ce projet."
You will generally also find an untranslated version of the new original text, e.g.:
#: ../../source/front/dedication.rst:11
msgid ""
"This book started as a simple Kickstarter project. The idea of writing a book and "
"making it freely available, under a Creative Commons license, was largely "
"inspired by the writings of Cory Doctorow and Lawrence Lessig. Their "
"message of sharing resonated very strongly with me. I'm not interested in "
"capitalizing on my knowledge of Modelica, I want to share it with others so "
"they can experience the same joy I do in exploring this subject. Happily, "
"this Kickstarter project was successfully funded on December 4th, 2012 and "
"my odyssey to create an entire Creative Commons licensed book began. If "
"circumstances had been different, this book would probably be dedicated to "
"Cory Doctorow and Lawrence Lessig for inspiring me to take on this project."
msgstr ""
(note the addition of the word "simple" in the first line)
The key point is that any previous translation is provided as a
reference (just commented out with #~ characters). Ideally
(assuming changes are small), it should be possible to reuse much of
the translated text. Unfortunately, I don't know if any easy way to
identify what change has occurred except by looking at both versions
of the original text and trying to identify the difference. But
hopefully we can avoid retranslations as much as possible.
If you would like to contriute to the translation effort but are not familiar with Git, this section will give a simple walk-through of using Git to translate the dedication.
It is worth pointing out up front that Git is not quite like other version control systems you might be used to (e.g., Subversion). This is because Git is a distributed version control system. What this means is that you will have your own copy of the complete repository for the book. In this section, we'll discuss how you should make your changes and what will be required to merge them into the book.
If you don't already have a GitHUb account, the first thing you will need to do is visit the Sign Up Page and register. Registering for GitHub is free.
Once you have a GitHub account, you should visit the main Modelica book page at http://github.com/mtiller/ModelicaBook. On this page, you'll see a "Fork" button in the upper right corner of the page. You'll want to press this button. When you do, GitHub will create a complete copy of the book repository under your own account. If you have any problems, you should consult the GitHub documentation on forking a repository for more details.
When this is done, you will have your own copy of the book repository. The page for your repository on GitHub will have an address like http://github.com//ModelicaBook. If you look carefully at the top of the page, you'll see that it says "forked from mtiller/ModelicaBook".
There are two ways to do translations. The first is "through the web". With this method you can simply edit the files you need to change directly from the GitHub web site. This might seem like the easiest approach, but it has some significant downsides as well that you will eventually run into. The other approach is to install a version of Git on your local machine and work with the files there. We'll discuss each approach. But in either case, the overall process is the same (see the Explanation section above).
To edit a file through the GitHub web site, simply go to your
repository page (remember: http://github.com//ModelicaBook)
and click on the directories: text, locale, the language you are
translating to (e.g., de, it, etc), and finally
LC_MESSAGES. The text/locale/<language>/LC_MESSAGES directory is
where all the translations are stored. To demonstrate web-based
editing, let's translate the dedication. From the LC_MESSAGES
folder, go to the front directory and select the dedication.po
file. You'll see a "read-only" version of the file. But if you click
the "Edit" button on the right side of the bar just above line 1,
GitHub will create an edit window.
Initially, you'll see text like this:
#: ../../source/front/dedication.rst:11
msgid ""
"This book started as a Kickstarter project. The idea of writing a book and "
"making it freely available, under a Creative Commons license, was largely "
"inspired by the writings of Cory Doctorow and Lawrence Lessig. Their "
"message of sharing resonated very strongly with me. I'm not interested in "
"capitalizing on my knowledge of Modelica, I want to share it with others so "
"they can experience the same joy I do in exploring this subject. Happily, "
"this Kickstarter project was successfully funded on December 4th, 2012 and "
"my odyssey to create an entire Creative Commons licensed book began. If "
"circumstances had been different, this book would probably be dedicated to "
"Cory Doctorow and Lawrence Lessig for inspiring me to take on this project."
msgstr ""
As described previously in the
Explanation,
our goal is to add translated versions of each line after the msgstr
token. Using the web-based editor, we turn the code above into:
"Ce livre a commencé comme un projet Kickstarter. L'idée d'écrire un livre et"
" rendant disponible gratuitement, sous une licence Creative Commons, était "
"en grande partie inspiré par les écrits de Cory Doctorow et Lawrence Lessig."
" Leur un message de partage résonné très fort avec moi. Je ne suis pas "
"intéressé par capitaliser sur ma connaissance de Modelica, je veux le "
"partager avec d'autres pour ils peuvent éprouver la même joie que je fais "
"dans l'exploration de ce sujet. Heureusement, ce projet Kickstarter a été "
"financé avec succès le 4 Décembre 2012 et mon odyssée à créer un Creative "
"Commons livre licence a commencé. Si circonstances avaient été différentes, "
"ce livre serait probablement dédié à Cory Doctorow et Lawrence Lessig de "
"m'inspirer de prendre sur ce projet."
Note that we do not change the English text. Instead, we simply
add the translated text after the msgstr token. Once we do, there
is a dialog at the bottom where we can commit the changes.
Once these results are committed, they will be added to the master
branch of your repository. To see how your repository relates to
other repositories you can visit the Network
Graph for the book.
To have your changes merged into the book repository (so they end up
in the book), you need to make a pull
request.
For the desktop process, you'll need to have Git installed on your computer. There are many different graphical user interfaces for different OSs and, of course, the command line tool. I can't provide detailed instructions for all of these, so I will stick with the command line tool. I suspect that most graphical tools also install the "git" command line tool somewhere on your machine as well.
To do desktop editing, you'll still need to create a fork as discussed
previously. Once you do, you need to clone the forked repository to
your local machine, like this:
% git clone http://github.com/<username>/ModelicaBook
From there, you should go to the LC_MESSAGES folder:
% cd ModelicaBook/text/locale/<language>/LC_MESSAGES
To use the same example as with the web-based approach, let's
translate the dedication. We find the translation file for the
dedication in front/dedication.po. So we can open this with a text
editor, e.g.,
% emacs front/dedication.po
Here was made the changes already discussed in the Explanation section previously. Once we have edited the file, we can check to see what modifications we have made locally by executing the following command:
% git status
You should see something like this:
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: front/dedication.po
This is telling you that you've modified the front/dedication.po.
But the changes still need to be committed. In Git, there are
normally two steps to putting your changes back into the repository.
But we can combine these steps like this:
% git commit -a -m "Updated the dedication"
The -a means "add" the files (the first step) and the -m is
followed by the commit message that explains what changes were made.
Even once this commit is done, nobody else can see these changes because they are still stored on your local computer. To make them public, you need to add them to your public repository hosted on GitHub. This is done by "pushing" your changes back out to GitHub with the following command:
% git push origin master
At this point, your changes are stored in GitHub. But you'll still want to make a "pull request"...
Once you have reached a stage where you would me (or the language
coordinator, if they are willing to take on this task) to incorporate
the results, you should send them a "pull request". This can be done
by returning to the main page for your ModelicaBook repository
(i.e., https://github.com/<username>/ModelicaBook) and clicking
the pull request button:
GitHub has step by step instructions on creating pull requests that might be useful here.
Generally, translators don't really need to worry about this step.
But in case you have all the tools necessary to build the book, the
following is a list of the various commands needed to build a version
of the book in another language. It should be noted that some of
these steps require installation of sphinx-intl. This can be done
using pip (e.g., pip install sphinx-intl).
% make gettext
% make update_all
% make buildmo
% make dirhtml_<X>
Currently supported languages are: cn, es, fr and de (e.g., make dirhtml_es)
% make server_<X>
Currently supported languages are: cn, es, fr and de (e.g., make server_es)