- 1 Introduction
- 2 Requirements
- 3 Write or update original doc
- 4 Translate an English doc
- 5 The script "Check_for_translation_works.sh"
- 6 Good habits
This page deals with the tools and processes to write and translate the Mageia documentation. Whilst primarily intended for use by members of the Doc team, all are welcome to read it.
If you aren't coming from this page https://wiki.mageia.org/en/Documentation_team, have a look on it. You will learn how to join the Doc team and how to subscribe the doc-discuss mailing list. It is the place to be to have all the needed information about works in progress.
Mageia documentation is written with Calenco. See the Calenco user's guide to find out how it works.
If we don't manage to communicate well with you, for instance if we've seen that we don't manage to explain you well enough how to correctly contribute to the wiki, then we first need to find a way to improve our communication.
If that isn't a problem and if you have done all of the following:
- successfully translated some of our .xml files by yourself after which they were uploaded to Calenco
- someone with Calenco access will download the needed .xml files for you, it is impossible to do that without credentials
- read the following:
then you can ask for credentials (a username and password) to access the Mageia Calenco repository.
The simplest way to get them is to send an e-mail to John at the address
"john At neodoc DOT biz" with a copy to
"marja11 AT xs4all DOT nl"
("AT" to be replaced by @ and DOT by ".").
This e-mail must include the following information:
- Your full name (given name + surname)
- The chosen nickname
- The language(s) you are able to work with.
- Your languages names in your own language or typeface so the language interface render correctly, e.g. in this form: Greek ελληνικά [el] or Estonian Eesti [et]
Very important information for translators is often given on our mailing list firstname.lastname@example.org.
If you never use your credentials to edit a file, or if you disappear and we don't manage to contact you, there is a grace period of 6 months. After that your Calenco account will be removed. Of course it will be possible to get it reactivated again if your absence was for good reasons.
Write or update original doc
Create a new page
1 - Open Calenco
- On the top right corner is a drop-down list of all the languages.
- On the left frame are the available folders.
- A list of all the English files appear in the middle frame
- Click on a file and check the Preview box to display its content. The text here is in read only mode, that is normal.
In the Classifications panel are four interesting folders:
- Draktools and its sub-folder DraktoolsScreenshots contains all the help files about the MCC
- NewInstallerText and its sub-folder (not really, but it should be) NewInstallerScreenshots contains all the help files about the Installer.
- DrakLive contains all the help files and screenshots about the Live Installer
- Boot.iso (former name for Netinstall) contains all the help files about the Netinstall (free and non-free) Installer. The ScreenShots are in the root folder, named All Files, because they are in English only and don't need to be translated.
2 - In the drop down list "Browse language" choose English (en). It is what is called the Workspace. The Mageia original documentation is always written in UK English and saved in the English (en) workspace
3 - Import a page with he correct new file name
Import the new .xml page with the menu File/Import File It doesn't have to be complete, yet, but it should at least contain:
<?xml version="1.0" encoding="UTF-8"?> <section version="5.0" xml:id="SOME_UNIQUE_ID" xmlns="http://docbook.org/ns/docbook" xmlns:ns6="http://www.w3.org/1999/xlink" xmlns:ns5="http://www.w3.org/1998/Math/MathML" xmlns:ns4="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:ns="http://docbook.org/ns/docbook"> <info> <title xml:id="SOME_UNIQUE_ID-ti1">Put the title of the page here</title> </info> <para>Put some text here.</para> </section>
4 - A preview is possible by checking the Preview box at the top of the screen.
Once the page created, Calenco alone isn't very friendly to write the page. So, others methods are suggested below. However, it is possible to edit a file with File/Simple Editor but keep in mind that the modification won't increment the version number! If it is important (the file has already been committed or it has already been translated for examples), you will have to download and upload to force the version number incrementation. The incrementation allows to return to a previous version.
Access to the existing English pages
Once the page is existing, there is several methods to access and modify it. Whatever your choice is, you must use Calenco to lock the file while you modify it using File/Lock. Don't forget to unlock it.
Calenco Simple Editor
As already said, it is not a good idea because of the versioning problem and it does not have Kate's XML parsing, code folding, autocomplete, highlighting, etc.
Calenco and XXE
XXE is a text editor and can be installed as a Calenco add-on. See here the how to :https://wiki.mageia.org/en/Translation_with_Calenco_and_xxe. This page was written for the Installer help writing but can be understood for any other work.
When it is done, you can select the file in Calenco and then, click on File/Full Editor to display the file in a new tab. This method correctly manage the versioning.
With this method you can access the distant files from your own file manager. It is then possible to write in the file with your favourite XML editor. No versioning problem since the dowload/upload ritual is inevitable.
A similar way to use webdav is to type this line in your file manager:
or in a konsole (using dolphin for example):
$ dolphin webdav://YOURLOGIN%40mageia.org:YOURPASSWORD@vargas.calenco.com:8284/workspaces/Documentation/classifications
YOURLOGIN and YOURPASSWORD must be changed by your own username and password. %40 must be preserved like that.
Optional parts in document
Some pages can be common in part to different manuals. This can be managed in a same XML file with optional entries. Then the publication will specify a condition to keep only specific parts.
To indicate that something is specific to a publication, you should add an attribute "condition" to this part. This can be a paragraph, a section, a picture for example. Look at this sample for alternative picture:
<mediaobject> <imageobject condition="classical"> <imagedata align="center" fileref="dx2-selectLanguage.png" format="PNG"/> </imageobject> <imageobject condition="live"> <imagedata format="PNG" fileref="dx3-language.png"/> </imageobject> </mediaobject>
In mediaobject, we can have dx2-selectLanguage.png if the publication transmits the "classical" condition, or dx3-language.png if the publication transmits the "live" condition.
See Calenco publications to know how to transmit the condition.
- First thing before create a new page is to be in contact with the doc team via the mailing list doc-discuss.
- The page filename must be chosen after the tool or command or installing step it is about. It must be decided with doc team agreement.
- Dito for new screenshots
- Screenshots are preferably lxh = 800x600 pixels, less for small images (don't oversize them), more if necessary for legibility.
- Screenshots format is .png
- It is possible to add links in the documentation towards Web, Wiki or Official documentation.
- Links towards Wiki must be a page title; subtitles, chapter titles and anchors are prohibited.
Screenshots are made with the wallpaper (on the left) and the Mageia logo but without pre-version add-on like sta1, RC, ...
For Installer help, that is updated for every new release, the wallpaper must be the new version one. For the other manuals, that are updated at any time, it is the current wallpaper.
Translate an English doc
Here is a flowchart of the translation process
The original texts in English are stored in the Calenco "en" workspace with the xml format. They are copied in the git repository where a script (see the Information below) creates the .po files that are at everyone disposal (no credentials needed). Everyone can download the .po files on his/her own PC and translate the strings in the xy language. At any time, the translator can upload the xy.po file to git, generate the .xml files and send them to git and also to Calenco with the screenshots. The red titles in the flowchart indicate the wiki pages that may help you to run these actions.
Create a new translation
Get the .po files and translate yours
Warn the doc-discuss mailing list about what you are doing in order to prevent somebody else to do the same job at the same time. You have also to fill the wiki page that manage the translating progress. For example, for the Installer and MCC help translations, it is this one Calenco_translations_report. (As we totally changed our procedure, an update is probably needed).
There is three ways to get the .po files, no credentials needed:
- Use git, see the wiki page Git_usage_for_l10n_and_doc to know how to dowload the .po files into your own computer.
- Use the script The script "Check_for_translation_works.sh", see the dedicated section below.
- Ask the wanted .po file to the mailing list, the simple way for the newcomers.
Once you have these files, you can select your language .po file and translate the English strings. Translating_with_Lokalize is a good idea, but any other preferred method is possible. However, keep in mind:
- You must preserve the attributes, their presence is shown by a bold or special font prints and also in the node path bar just under the tool bar.
- You must preserve the tags (like xref for instance)
- You must not translate the key words like Warning, note,
- You must not translate the file names (of the images for instance)
- You must update the related board
Send the po file to git
No need to have finished the whole .po file translation to send your work. The not translated strings will continue to be displayed in English, so even a small contribution is better that nothing.
You have now to send back the .po file in the git repository (action called "to push"), see Git_usage_for_l10n_and_doc if you have the credentials or send the .po file to the mailing list asking for somebody to push it.
Send the xml files and the screenshots into Calenco
You have also to convert your translation for uploading into Calenco and git, for that enter the directory you found the .po file and type:
Example for an Estonian translator:
For those who get the .po file from the ml, you can find the script makedoc.sh here
Here is a screenshot showing the script makedoc.sh in action, you can see an extract of the list of created .po files.
From only one .po file, the script re-write a lot of .xml files. Only the .xml files you worked on are to be taken into account for the following.
Check that all the files (xml and screenshots) have strictly the same name in your language that the original ones.
Now, open Calenco and take care to be in the right workspace and the right folder. The screenshots aren't in the same one than the xml files. Then just use the menu: file -> Import a file and use the browser to find the file to import.
In case of error, select the file and click on File management to delete it or move it into another classification.
Send the xml files to git
You have now to send back the .xml files in the git repository (action called "to push"), see Git_usage_for_l10n_and_doc if you have the credentials or send the .xml files to the mailing list asking for somebody to push it.
Access to the existing translated pages
Don't use Calenco any more to make or modify translations, use git or The script "Check_for_translation_works.sh" instead, here are the URL for the Installer and mcc-help:
To know more about git, please read: https://wiki.mageia.org/en/Git_usage_for_l10n_and_doc
Work actually in progress
At the beginning of the year 2013, the Draktools help is in progress: https://wiki.mageia.org/en/Calenco_Draktools.
You can contribute for more languages. Some updating will be made for Mageia 4.
We try to keep our Calenco translations report up-to-date.
The script "Check_for_translation_works.sh"
This script is a great help for translators as in one click it installs on your PC:
- The files from git, like using git clone
- The files from svn, like using svn check out (used in the past for web pages so script needs to be updated as they now use git too)
- The translations folder, it is a working directory used for example by Lokalize
- The file list_of_resources_for_translation_your_language_code.txt that lists all the strings that need to be translated or updated in your language
Fetch and configure the script
The script and the README files are available here: http://gitweb.mageia.org/software/i18n/tools/tree/
Before you run the script please see its README. After the first run, the config file ~/.mageia-i18n-config is created and you must configure it according to your wishes. You can also edit it at any time.
Apart of language code that needs to be set, there are also git and working directories that must be entered.
Use of working directory is very recommended as it separates translation and version control system (svn and git) so that they don't mess in each others work flow. If you're sure that you still don't want to use working directory at all you need to exclude copying all types of resources (po, desktop, html and website pages translations).
Recommended configuration for docteam
Change only the lines into your configuration file from this example that apply to you:
work_on_desktop_files=no # use this option to exclude work on software desktop files resources (icons in desktop environments) # work_on_desktop_files implies copying_desktop_files: copying_desktop_files=no # use this option to exclude copying of translations of icons in desktop environments work_on_html_software_files=no # use this option to exclude work on html software resources for gfxboot help # work_on_html_software_files implies copying_html_software_files: copying_html_software_files=no # use this option to exclude copying of html software resources for gfxboot help work_on_unofficial=no # use this option to exclude work on unmaintained/unofficial software resources work_on_mga3=no # use this option to exclude work on software resources for mageia 3 branch work_on_web_pages_translation=no # use this option to exclude all work on website pages translation # work_on_web_pages_translation implies copying_wp: copying_wp=0 # use this option to exclude copying of website pages translation resources
Recommended configuration for translators
If you'll use svn which is now used only for web pages translation you must also configure svn method and set svn directory.
Other than that you can use default configuration but in case if you want to exclude work on documentation resources just change this lines into your configuration file:
work_on_docs_and_tools=no # use this option to exclude work on documentation resources
Run the script
Each time you run the script, it gives you a lot of comments, at the end you have the TODO list in orange prints. This list in this example is saved in i18n/svn/list_of_resources_for_translation_your_language_code.txt.
Here is an example of using the script for translations in French.
You can see:
- the three folders git, svn and translations in the file browser
- at your right hand, the file i18n/svn/list_of_resources_for_translation_your_language_code.txt that contains the "TODO list".
- at the bottom, the end of the comments (in white), some information (in green) and the beginning of the "TODO list" (in orange)
Use the results
You have now the three folders: git, svn and translations
git is the Mageia repository for all the software and the web pages (note that the script needs an update for that to work properly). svn was the Mageia repository for the web pages. If you know them, all the git and svn usual commands are valid in these directories. The script filled them according to your wishes in ~ /.mageia-i18n-config
translations is the working directory, the place where the translator works, it is safer to work outside of git and svn directories. translations contains only the xy language (xy.po files). In each translations subdirectories, there are two .po files. The file xy.po is a direct copy from git. File <subdir>.pot_xy.po is created for the translator as a working copy of xy.po. When you translate you'll edit that one and rename it before to push it (or send it to the ml).
Run the script again to update
- -> subscribe and follow the doc-discuss ml
- -> warn in the ml before start writing/translating/upgrading files, above all if you weren't the writer
- -> ask help in ml