Meta:Guides/Translation Guide

General Rules

We welcome localisation of the Core Documents and provide place within the wiki as long as the abide to the following rules:

• Localised versions have the same license than the main, Official, English version.
• Localised versions conforms to the style guidelines detailed on this wiki.
• Localised versions are a translation of the Official English documentation

This last point is very important, Blender Documentation must be in English because English is the language we all understand (more or less) whereas any other language is less “universal”.

It is hence mandatory that no localised version contains more information, not even more updated information than the English version.

We are of course aware that the English version is not fully up-to-date. If any editor of a localised version is in need to update a part of his/her documentation we kindly ask him to update the English part first and the localised part later. We do believe that the all of us can write acceptable English, and there are Native English speakers around to fix spelling and grammar. Anyway, in the case a localised editor really don’t feel like putting his hands on the English Official documentation please join the #blenderwiki IRC channel and describe what you’d like to have updated to some English writer.

When you are not sure whether you understood a sentence (or a whole paragraph) well or not, you should put it next to your translation, in italic, following this scheme: [translation] ([small note of the translator explaining the problem] “[the original text, in italic]”).

Here is a (french) example:

Ceci est un exemple (NdT : phrase originale : “''This is an example''”).

Which gives: Ceci est un exemple (NdT : phrase originale : “This is an example”).

When you do not understand a sentence (or a whole paragraph), just leave the English version, in italic, with a small text explaining the problem.

Do not try to translate something you really do not understand! This would likely lead to an even more confused and un-usable translated version of the text…

When you find a text that you hardly understand, and think it’s because it is quite unclear, you should try to re-write it in the English page, or ask someone to do so, before translating it, as it is rather unlikely that an unclear original text results in a clear translation!

As a final word, and even if it might seem obvious, you should avoid to translate texts that you do not truly understand in depth, I mean, not only linguistically, but also technically (this might even be more important)… In fact, you should know at least the basics about Blender!

Page Name

Keep the naming scheme exactly the same as the English pages, and add your language code between the namespace (the small string before the first “:”, like “Doc” in “Doc:Manual/Data System/The Outliner”) and the page name (“Manual/Data System/The Outliner” in our example).

When you start a new translated page, please click on the link of the English page to see the new pagename and add your language code to this new URL.

For example, say you find a link like “Manual/The Outliner” somewhere and you want to start translating it in Brasilian Português. Click on it, you will find it is now called “Doc:Manual/Data System/The Outliner”.

Add the “PT/” to this new pagename so that is becomes “Doc:PT/Manual/Data System/The Outliner”.

These guidelines are explained also here.

Don’t translate the page name! Keep the pagename in English! This helps us to understand what’s the reference English page, and later it will help to make some automation on URLs in templates.

Images Names

Use the English images, they usually do not need to be localised, be kind to our server!

Links to non-existent pages

If a page doesn’t exist then don’t link it, so that we avoid those awful green- or red-links.

For all non-existent pages, readers should see both the translated title and the link to the English page (i.e. see Doc:DK/Manual).

For example, if Doc:Manual/Vitals/Screenshots isn’t translated in Brasilian when you link to it, you should put:

:Screenshots - [[doc:2.4/Manual/Vitals/Screenshots|eng]]

…so the reader see that there isn’t the Brasilian page but he can go to the English one. The translators should change that into

:Capturas de tela - [[doc:2.4/Manual/Vitals/Screenshots|eng]]

Once the page gets translated this link should become

:[[Doc:PT/Manual/Vitals/Screenshots|Capturas de tela]]

Technical terms

In general, the technical terms used in CG are quite new or even downright neologisms invented for the needs, so they do not always have a translation in your language. Moreover, a large part of Blender users uses its English GUI.

As a result, unless a term has an evident translation, you should preferably use the English one, putting it in italic. You can then find a translation for it, which you will use from times to times (e.g. to avoid repetitions…). This is also valid in the other way: even when a term has a straightforward translation, don’t hesitate to use its English version from times to times, to gets the reader used with it…

If a term is definitively not translatable, just give its definition one time (per pages, preferably), then always use its English version.

See also your glossary (if there is any for your language - if no, it might be a good idea to create it!).

By the way, you should always keep the English version for GUI items (control names, menu items, …), for the same reasons exposed above.

Keeping Pages Up To Date

In order for translators to keep pages up-to-date, it is important that they add the English version of each page to their watchlist. There are two ways to add a page to your watchlist:

• Press the Watch tab at the top of the page, or…
• When editing a page, check the Watch this page checkbox before submitting.

In your user profile, there is an option to default to watch any page you edit. Choosing this option is recommended.

When you have a set of pages in your watchlist, every time you come back to the site you can view your watchlist by clicking the My watchlist link in the upper right hand corner. The watchlist will show you only the recent changes to the pages you watch. From there you can easily go and see what changes were made and decide if the changes warrant translation. In your profile, you can also set an email address where emails can be sent when your watched pages are edited by someone else. This setting is also recommended.

You will need to coordinate with the other translators of your language and decide who should maintain each page. You will also need to keep your eye on the New Pages list to be sure someone is assigned to watch and maintain each of those new pages.

Progression bar in “Page/Header” template

No examples I have removed the examples, as they do not work in english pages (they need to be put in a page which name is starting with a language code). You can see examples of what it looks like in the french page.

In localised pages, the “Page/Header” template takes an extra parameter, a number between 0 and 100 which represents the level of completeness of the translation:

{{Page/Header|2.4x|Doc:FR/Manual/3D interaction/Manipulation/Transform Orientations|Doc:FR/Manual/Data System|0}}
{{Page/Header|2.4x|Doc:FR/Manual/3D interaction/Manipulation/Transform Orientations|Doc:FR/Manual/Data System|39}}
{{Page/Header|2.4x|Doc:FR/Manual/3D interaction/Manipulation/Transform Orientations|Doc:FR/Manual/Data System|100}}

By default (i.e. if you do not specify a number), a zero value will be used:

{{Page/Header|2.4x|Doc:FR/Manual/3D interaction/Manipulation/Transform Orientations|Doc:FR/Manual/Data System}}

How it works Basically, the template detects if there is a language code as first part of the current page name. If not (english page), it do not show the progress bar.

“oldid” in “Page/Header” template

No examples I have removed the examples, as they do not work in english pages (they need to be put in a page which name is starting with a language code). You can see examples of what it looks like in the french page.

There is also an option in the “Page/Header” template (the one you are supposed to put at the beginning of all the manual pages…), called “oldid”. This allows you to put the ID of the (English) page version against which you made your translation, as a reference. Here is how to use it:

1. When editing the localised version, add in your header template an “oldid” option, like this:

{{Page/Header|2.4x|Doc:FR/Manual/3D interaction/Manipulation/Transform Orientations|Doc:FR/Manual/Data System|100|oldid=}}

1. Go to the English version of the page, and copy the address of the Permanent link, in the right sidebar.
2. You will see that this url ends with something like “&oldid=12345”. This is the number (the ID) you have to copy in the oldid option of your template, to obtain something like that:

{{Page/Header|2.4x|Doc:FR/Manual/3D interaction/Manipulation/Transform Orientations|Doc:FR/Manual/Data System|100|oldid=12345}}

Note the white little arrow in the progress bar: it’s a link that will lead you to a “diff” page between the English version corresponding to this ID, and the current English version of this page. Most useful to quickly see if something has changed, and what, since the last translation of a page…

People

We need to appoint “managers” for each localised version, so to know whom to bug for problems. The correct way of doing so is to edit the relevant line in this table.

Interface Internationalization

Please refer to this page.

References

• List of ISO country/language codes.
• The country flags.