Translations (how to handle, design task)
Closed, ResolvedPublic

Description

Current Status


We need to formalize how to handle translations. Follow up on http://lists.blender.org/pipermail/bf-docboard/2014-November/004600.html.


Translation Workflow

The sphinx-intl project is well supported and has been tested to work with a snapshot of the Blender-Manual.

Rather than having multiple separate manuals, we would instead maintain translated strings (common for translating applications).

See: sphinx-intl https://pypi.python.org/pypi/sphinx-intl

basic workflow is:

  • Generate POT files
  • Generate language specific PO files.
  • PO files are committed to source control (we might have a separate repo for these)
  • Translators edit PO files (tools like https://poedit.net// are apparently good).
  • Docs can be built with a translation applied.

Web Based Translation Software (currently not in use)

Eventually, we may want to look into using web-based translation software.

Some existing software exists:

Details

Type
Design
Sergey Sharybin (sergey) triaged this task as "Normal" priority.Jan 1 2015, 11:07 AM

ok, thanks for redirecting this one. :)
I'll start here again:

v2.73: "Help --> Manual" goes to a new manual with no translations

I understand this is a new (under development) version of the Blender manual and that in the long run it will be better.
But right now the fact is that we (non-English users) are losing an old translated manual in favor of a new English-only manual.

I (as a Blender instructor) am not happy with it.
There's no way now for unexperienced non-English users to easily access localized help.

Perhaps, in the mean time, a solution woud be to have a home page in that new Manual, with a clear route back to the previous translated versions of the manual?

Thanks!

This comment was removed by Campbell Barton (campbellbarton).
Campbell Barton (campbellbarton) changed the title from "How to handle translations" to "Translations (how to handle, design task)".Jan 20 2015, 2:00 AM
Campbell Barton (campbellbarton) changed Type from To Do to Design.

hi,
Really a bad old news.
I can't always be in english manuals.
Sometimes I need to translate a text before understanding it.

We have waited for months, now change your politics.
Thanks.

Hello,

Have some thoughts about documentation handle:

  1. Each module, unit or addon must have some basic code in English for general wiki and autodoc system.
  2. Create system of hierarchy for all blender units and parts.
  3. That hierarchy must be autoactualizing on base English.
  4. Abstract module must be attached to all ui elements - animation module for visual explanation of function or feature.
  5. Create general documentation database for all created docs and pages. It must always autocompleting and self-actuating via autoscan or manual adding in string-based html fields. Later it is possible to create all html files from database fields via special forms basically in English.
  6. For each old doc must be one record in that database. All html files must be archived in general repository for request for database-creation time.
  7. Then, for translator accounts will be created task for translation on own language from that database. Each task must be connected to basic record, so each string-field have corresponding local string-field.

Hope this will be helpful.

@Vyacheslav (slone). Sphinx provides a translation system already - I've tested it and it works well as far as I could tell,
I think we just need to start using, with someone who's prepared to be the first person to hit any issues we might run into.

hi,
Really a bad old news.
I can't always be in english manuals.
Sometimes I need to translate a text before understanding it.

We have waited for months, now change your politics.

Thanks.

This isn't about politics, the English manual was being heavily edited, pages removed/moved/split/merged, so having translations keep up with this would have been problematic.

I think we're slowing down on this - so we could trial translating some chapters now.

Ok, I see. If I can help to this somehow I will be glad.

One more thought about translation proccess:

  1. Maybe it will be convient for translators to use only one portal user-friendly simple web-form connected to all translation database.

It is very difficult to understand something when we have to do many actions and searches to translate something. It is difficult to find what to translate at all. So for newbie it is hard to envolve in this proccess in double measure.

  1. It can be organized as a list of today's tasks. Something like a simple guide can be very helpful to start. And of course web-form must be translated on native translator's language to help him to start. For many people it is very hard to comprehend a lot of English-text data.
  2. All programming and coding must be hidden to not to confuse a translator. He sees only that what he can do as a translator, no more. But he always can go further to get more specific programming data but only if he can understand it by own request.
  3. All translator's history can be stored as in github or something like that to check and moderate.
  4. All translation system must be centralized and connected to coding system for adminstrating. Internal implementation must be hidden and be accessible only by special request.

I'm not expirienced in Sphinx but probably it is a tool that can help. These thoughts I have from my php-programming experience and usability considerations.

@Vyacheslav (slone):
Some web based translation is possible, projects exist, noted in original post.


But setting these up takes some investigation, we can do it, but this needs to be configured to our own needs.
Probably to begin with we will just use SVN directly, and after that works on a basic level, investigate online options.

Hi,
I am willing to translate the manual in french. So I updated the makefile to make things easier. See :
https://github.com/libellul/blender-manual-fr/commit/377e8fb329e1a65d1fcb265ed4c3d34f304f1780

for translating in french you have to do

  1. MANUAL_LANG=fr make update_locale
  2. translate
  3. MANUAL_LANG=fr make

That's it you have you manual translated and builded.

Since I want to do my translation, I'll do it on my github. It won't be hard to port it to the subversion repository.

Anyway I will keep you in touch from any problem I'll encounter

Hi, @Libellule (Libellul), We'll be looking to add the translation repository soon (next few days... end of next week latest).

Update, committed initial French translations to: https://developer.blender.org/diffusion/BMT

@Libellule (Libellul), I've added you to the documentation project so you can commit changes to this repo.

Hey there Cambo, there seems to be someone willing to translate to Russian and Ukrainian. How do we proceed in this case? Simply add a ru directory in the repo?

Hi Campbell I can't commit my changes to the documentation repo

@Libellule (Libellul), to handle issues with commit access, best do this via IRC (#blenderwiki on freenode) or the bf-docboard mailing list.

Post there what errors your seeing and we can try to resolve.

(Rather keep this task for feedback on translation process, troubleshooting individual users commit access here is off topic).

Hello, Campbell!
I want to take part in the translation of documentation into Russian.
But I can't commit changes documentation repo.

Hi,
I wanted to know if we can regenerate the po files for our language. I stumbled upon a page where strings have changed and it's a bit frustrating.

I have also a suggestion
It would be nice to have tool using git/svn blame to keep track of outdated translations.
I think it's better to have a partial but updated documentation than the opposite.

I don't know anything about python but if there's really nobody who want to do this job I'll take a look

But maybe I'm wrong and there's a simplier way to track outdated translations

Who should be responsible for doing these normal? Documentors or Translators?

Hey @Sergey Klimkin (Sergey_Klimkin), I've added you to the documentation project, so you can now commit PO files (and edits to the manual too) using subversion.

@Libellule (Libellul), I run an update on the PO files around ~weekly, the manual isn't changing so fast that this is normally a problem. (committed update),

To do this yourself, see:
https://www.blender.org/manual/about/translations.html#updating-po-files


@Aaron Carlisle (Blendify), Anyone can do this, however it may be a hassle to setup, so I don't mind to do it weekly.

Hi,
I thought I had outdated po file but I was wrong.

The file concerned is getting_started/installing_blender/installing.po
https://developer.blender.org/diffusion/BMT/browse/trunk/blender_docs/locale/fr/LC_MESSAGES/getting_started/installing_blender/installing.po;69$67

At this line msgid tell us we sould find the string "Daily Build" at line ~32 in the documentation file.

And here is the line in the documentation (which hasn't bee updated since 09/15/2015)
https://developer.blender.org/diffusion/BM/browse/trunk/blender_docs/manual/getting_started/installing_blender/installing.rst;1018$31

"Latest Stable Release <http://www.blender.org/download/>__"

If I update the pos files following exacty the instructions of blender documentation I get the string
msgid "Latest Stable Release <http://www.blender.org/download/>__"

Good !

But what about the next time you update the po files won't the "wrongs msgid" be merged, replacing the good one ?

@Libellule (Libellul), not sure what you mean - merging changed can be problematic - but in general updating the PO files shouldn't be causing continual errors, or this would be an unusable system.

I've updated the PO files since your post,
if you see an update that causes problems - let us know.

@Campbell Barton (campbellbarton), Don't mind the merge problems it's a misunderstanding.
You have updated the PO File but it did not updated the mentioned string

Here is what I understand :

  1. In the install.po I have this line :https://developer.blender.org/diffusion/BMT/browse/trunk/blender_docs/locale/ru/LC_MESSAGES/getting_started/installing_blender/installing.po;89$89 it does not match the string in https://developer.blender.org/diffusion/BM/browse/trunk/blender_docs/manual/getting_started/installing_blender/installing.rst;1018$31
  1. If I Translate this string and build the manual the string stay in English which is predictable.
  1. If I update po files I get the good string : https://developer.blender.org/diffusion/BMT/browse/trunk/blender_docs/locale/fr/LC_MESSAGES/getting_started/installing_blender/installing.po;89$155
  1. If I translate the string and build the manual again the string is translated.

What I do not understand :

  1. @Campbell Barton (campbellbarton) you keep updating locales with the wrong msgid
  2. I committed my local change that worked on my computer. But build on the online manual the string is kept untranslated.
  3. The German team Choose to ignore this problem (was there even one for them ?) And Translated it : https://developer.blender.org/diffusion/BMT/browse/trunk/blender_docs/locale/de/LC_MESSAGES/getting_started/installing_blender/installing.po;89$90

Guess what ? It worked

I think I'll wait for your next repositories update and do as the German team. But I think there is definitely a bug and it's not on my computer

Sorry for the annoyance

@Libellule (Libellul), I ('the german team') didn't realize it, when I translated it;
but you're definitely right (and it isn't just you):
The msgid should contain hyperlink, but doesn't.

Direct (visual) comparison:
https://www.blender.org/manual/getting_started/installing_blender/installing.html#download-blender
https://www.blender.org/manual/de/getting_started/installing_blender/installing.html#download-blender

The English version has three hyperlinks, the German only one.

Merry Christmas everyone,
Anton Felix Lorenzen

Hi, I've started the chinese translate process for four or five months.
The work flow is : sphinx-build -b gettext produce pot then sphinx-intl update produce po file, then distrubute po file for someone translate then collection them to build html . I'v enconter so many problem and solved,especially the old sphinx-intl can't distinguish changed url item give me a new item in po, but the new one change the exist item and mark then as fuzzy item. this can reduce my work load.
Question is could I upload po files to repository and how. then can automatic build htmls.
I use sphinx-build -b html -D language="zh_CN" to build html.
thanks.

@Anton Lorenzen (anfelor), @xueke pei (yuzukyo) - if theres problems, please report bugs to: https://github.com/sphinx-doc/sphinx-intl
(noting them here is fine too, but best make reports to have them fixed).

I reported the bug I mentioned to sphinx-intl and it has been fix.

Also what software do you use for translating ?
And Have you any feedback to do about it ?

@Libellule (Libellul) could you give a link to that report you made thanks

@Libellule (Libellul) we updated to Spinx 1.3.4 you can update yours by running pip install -r requirements.txt Then run pip install -r requirements.txt --upgrade Does every thing work currently now?


Make sure you update SVN also

@Aaron Carlisle (Blendify) : short answer yes
long answer :

  • I updated sphinx-intl with pip install -U sphinx-intl (not sure if it's mandatory).
  • I updated the po files
  • I removed the old lines commented out at the end of the file with a text editor because poedit was complaining about errors.

It's ready for translation !

Hello
I need help
I'd like to translate but each time I try I fail

I'm on linux, I use poedit
I translated manual/advanced/index.rst
I have an index.po ( http://dindoun.free.fr/DIVERS/index.po )

To install i did that :
svn checkout https://svn.blender.org/svnroot/bf-manual/trunk/blender_docs
cd blender_docs
pip install -r requirements.txt
pip install -r requirements.txt --upgrade
make

svn update
svn checkout https://svn.blender.org/svnroot/bf-manual-translations/trunk/blender_docs/locale/fr locale/fr
svn update

change the .po
make gettext
sphinx-intl update -p build/locale -l fr
sphinx-intl build
make -e SPHINXOPTS="-D language='fr'"

I probably made 1 or 2 more make

please mp to dindoun at free.fr

I try this :

svn commit locale/fr/LC_MESSAGES/advanced/index.po -m "advanced" --username "dindoun"

it seems to work :) . Do I have to wait for something or commit the .mo too?

Another thing : I'd like to help for the python scripting help

Your commit made it through see https://developer.blender.org/rBMT255

Do I have to wait for something or commit the .mo too?

No these are made from the server side and your page is translated https://www.blender.org/manual/fr/advanced/index.html

Ok , thanks.
Now I'm ready for the translation.

It worked, but

It seems to have now errors I don't understand :

this : https://www.blender.org/manual/fr/physics/force_fields/introduction.html exists
but on this https://developer.blender.org/diffusion/BMT/browse/trunk/blender_docs/locale/fr/LC_MESSAGES/physics/ I can't see force_fields

PS
when I read, if I see errors in English : what must I do?

You also have commit rights to the English versions. As for the other issue I do not see anything wrong. Maybe @Campbell Barton (campbellbarton) can help

There was an error in the translation updating script, new directories weren't being added to svn. Fixed rBM1682. rBMT262.

Thanks
it seems to work :)

few things :

I have a probleme with this ligne :
"A detailed guide that covers every setting with images and examples <https://www.miikahweb.com/en/articles/dynamic-paint-guide>__ (Currently not up-to-date)"
in
locale/fr/LC_MESSAGES/physics/dynamic_paint/brush.po

poedit always say "double définition de message" ( ~ duplicate message definition ) but all work .

On the blender interface in french , the translation is not finished.
To be useful, I use in my traduction, the terms I see in the interface ( the same title even if it is approximatif )
Is there a way to automatically put the terms of the interface in the traduction ( so if they change in the interface they will be changed in the manual )?

What must I do to put a reference to the french images ( with the french traduction in the images ? )
I tried a directory blender_docs/locale/fr/LC_MESSAGES/images/ with
blender_docs/locale/fr/LC_MESSAGES/images/physics_dynamic-paint_brush.jpg for
blender_docs/manual/images/physics_dynamic-paint_brush.jpg
but I see english images in the french traduction

Following the force_fields :
I can't commit the files : it says

svn commit locale/fr/LC_MESSAGES/physics/force_fields/ -m "forcefields2" --username "dindoun"
svn: E200009: Échec de la propagation (commit), détails : 
svn: E200009: '.../blender_docs/locale/fr/LC_MESSAGES/physics/force_fields' n'est pas versionné

I tried a

svd add locale/fr/LC_MESSAGES/physics/force_fields

and the commit says :

svn commit locale/fr/LC_MESSAGES/physics/force_fields/ -m "forcefields2" --username "dindoun"
Ajout          locale/fr/LC_MESSAGES/physics/force_fields
svn: E155011: Échec de la propagation (commit), détails : 
svn: E155011: Répertoire '...blender_docs/locale/fr/LC_MESSAGES/physics/force_fields' obsolète
svn: E160020: Path already exists, path '/trunk/blender_docs/locale/fr/LC_MESSAGES/physics/force_fields'

Not sure what is wrong. I would try:

  1. svn cleanup
  2. then update your branch and try again

hi ,
still doesn t work
but I'm not sure of update your branch : I just update with svn update

I'm not sure I did

python3 tools/report_translation_progress.py locale/fr/LC_MESSAGES/

as proposed in https://www.blender.org/manual/about/translations/contribute.html#translations-fuzzy-strings

It works but I had to destroy my directory avec make another one

Maybe useful : my command line in linux ( after I've translated a po with poedit ) to see french traduction in local network

cd ~/Bureau/TraductionDeBlender/blender_docs && make gettext && sphinx-intl update -p build/locale -l fr && sphinx-intl build && make -e SPHINXOPTS="-D language='fr'"

then to see french traduction on blender.org

svn commit locale/fr/LC_MESSAGES/physics/fluid/ -m "fr-fluid-more" --username "dindoun"
  1. As soon as I translate alone it's simple, but if someone come to translate, what will I have to do to download his .po in the french directory?
  2. When a .rst is changed after a svn update, is the french .po changed also?

Hi
what must I do when Isee errors in the translate in frence interface?
For example in "Baking Physics Simulations" (baking.po) we can find the traduction of light as lumière(not dark)
but in french we have to say léger (not heavy) .

And badder the traduction of Heavy is Compact !

As soon as I translate alone it's simple, but if someone come to translate, what will I have to do to download his .po in the french directory?

You will have to update your local SVN

When a .rst is changed after a svn update, is the french .po changed also?

These are updated with the a script. You can either do them yourself or wait for @Campbell Barton (campbellbarton) to update them.

see also: https://www.blender.org/manual/about/translations/contribute.html#updating-po-files

what must I do when Isee errors in the translate in frence interface?

I do not know if this is exactly what you are asking. If there is an error you can fix it and commit the change.

I'm a newbie in svn
I have always errors on my local base and I must sometimes delete all the directory and then I must download all the files to be sure. But after that it works.

  1. Sometimes I read and translate things which should not be there. For exemple on https://www.blender.org/manual/fr/physics/introduction.html they were something about mars to delete in the english .rst and so on my french .po. ( someone has seen it )

May/must I change it on the original .rst ? I thought it was for another project or "team".
Maybe I could say it to someone each time.

  1. Sometimes I translate words from the interface which are not the good translated words ( or simply I don't agree ) but if I use the good one ( my good one ) it will be different from the interface.

Maybe I could say it to someone each time.

  1. when someone changes a .rst ( like the one on mars ) nothing say it to me. Is there a way to know it automatically ( with svn I suppose?)

I have always errors on my local base and I must sometimes delete all the directory and then I must download all the files to be sure. But after that it works.

This sounds like you are looking to use svn revert. If you are new to SVN and not good at using a command line version, I recommend using a SVN client with a graphical interface. For example, I am on windows and have two clients installed. One is a basic command line tool and the other is Smart SVN

Sometimes I read and translate things which should not be there. For example on https://www.blender.org/manual/fr/physics/introduction.html they were something about mars to delete in the english .rst and so on my french .po. ( someone has seen it )

May/must I change it on the original .rst ? I thought it was for another project or "team".
Maybe I could say it to someone each time.

If you have the original RST files you also have commit rights to that repository. Simply follow the contributing to the manual guide:
https://www.blender.org/manual/about/contribute.html

Sometimes I translate words from the interface which are not the good translated words ( or simply I don't agree ) but if I use the good one ( my good one ) it will be different from the interface.

I would use whatever the translated interface says.

when someone changes a .rst ( like the one on mars ) nothing say it to me. Is there a way to know it automatically ( with svn I suppose?)

I just pay attention to https://developer.blender.org/audit/query/ji9F0ABm_HOP/#R

I want to take part in the translation of documentation into Russian. But I can't commit changes documentation repo. Please add me to the documentation project.

I added you. Username and password are the same has what you used on this website.

Aaron Carlisle (Blendify) closed this task as "Resolved".Apr 14 2017, 9:22 PM
Aaron Carlisle (Blendify) claimed this task.

Marking as resolved, for the most part, we have the workflow together. If people are interested in joining the project please follow the steps on Documentation and email the mailing list.