How can we help doc translators?

[wouterj]

The doc community (you!) are really active. That's very great: Symfony is one of the most actively maintained documentations and is moving towards almost 100% feature coverage!

However, there is also a downside on this. A downside where @gregquat and @garak can tell you a lot more about. The translators simply can't keep up with the pace. It so worse, we even have to "highly recommend against creating new translations". I just had to remove 2 other translations because they are simply dead: #4077

And that makes me really sad. Translations are meant to get "the Symfony word" to even more people. But at the moment, they just provide outdated docs. That's really demotivating for the few translators that still work on their translations.

What can we do about it? How can we motivate people to work on their localized docs as active as they do on the english version? Is there maybe another way of providing a translation? How do other big, active, projects manage this?

Or should we just stop translating the official docs and promote people to write Symfony tutorials in their own language on their blog? Should we maybe create a section on symfony.com with localized, proofreaded, tutorials?

(this is tagged as DX because i18n is a big part of the experience for people)

/cc @fabpot, @javiereguiluz

[javiereguiluz]

I've thought a lot about this in the past. The last time was when we redesigned symfony.com. My opinion is 100% in favor of this:

Or should we just stop translating the official docs and promote people to write Symfony tutorials in their own language on their blog?

[gregquat]

Hi,

IMHO, stop translating isn't the best solution. There are already many bloggers who write cool tuto/cookbook/tips on Symfony and Javier's job about this is really useful.
However, I think blogs are even less maintained than our official doc (I mean, the French doc for example). Of course, when you visit a blog, you are aware that it can be outdated whereas you except an official doc to be always up to date.
Another point is blogs won't be as complete as the official doc. Many people would write a blog post about form rendering for example, but few of them would write about security. Finally, the official Symfony documentation is very well referenced on Google, blog post won't be as easy to find.
Promoting people to write blog posts is a good idea, but I think it should be in addition to the official doc.

Personally, I'm still motivated, but I haven't enough time to keep the documentation up to date. I've seen some improvement since a "Edit this page" button has been added on Symfony.com. It was really a good idea to ease people fixing/updating the documentation.

Another "important" point (I put some quotes as I don't know how important it is) is translators are not valued (maybe the word is not correct). I mean, some of the French translators have asked for Sensio Connect Awards. There are awards for English contributors but not for translation contributors (if I'm not mistaken).
The number of commits and changes are also listed on a Symfony.com page but the translation commits are not. I don't know if many people are helping for these reasons, but maybe it can motivate some of them to help.

Another idea is to improve our tools. Actually, it's very hard to follow English PR and update the French doc. It's a manual process. @alexandresalome and other developers have started on a project (https://github.com/alexandresalome/symfony-doc-synchronizer) to ease the detection of outdated documents. I must also work on it and deploy it "soon".

[ricardclau]

I am generally 👎 on translating official docs.

Like it or not, English is the default language of the industry and it is a titanic task to not only translate all the docs but to keep them up to date.

With my biggest respect to @gregquat @garak and many others, I am with @javiereguiluz on this one

[fabpot]

Let's face it, the activity on the Symfony docs (English) is just outstanding. It's really unbelievable what the doc team achieves. If you want to maintain a translation of the docs, you need 2/3 full-time people working on the translation and committed to do that for the foreseeable future. I think this unrealistic in the long run.

And when docs and desynchronised, it's worse than no docs. We official give wrong documentation to our users, that's not really acceptable. @alexandresalome recently worked on a way to display a message when a translation is not up to date on symfony.com but that does not work very well as if someone fix a typo in the French version, it will be considered fresh even if major changes occurred in the English version.

The idea of having translations for the docs is appealing but let's be honest it, that's just not possible because of the awesome job done by the English doc team.

[fabpot]

Don't get me wrong, I really appreciate the work done by the translation teams, but I really think this is a lost battle. What about limiting the translation to some sections of the docs? Would it make sense?

[garak]

What about pointing out that translation are unofficial? Something to say "this translation should be accurate, but the best source is original documentation". Just like GPL.

[gregquat]

@fabpot, you're right when saying it's a lost battle. The English team is working very hard and very fast and we can't follow. Maybe the best idea is the @garak's one : mark the translations as "unofficial" or "potentially outdated, use it carefully".

Translating only some section is a good idea too. We could focus on the Book and the Quick Tour only. But some really useful information are also in the Cookbook and References so... how to choose the sections to translate?

[xabbuh]

I think we should consider first which groups of people actually read the translated documentation. From what I see, each reader roughly belongs to one of the following groups:

1. People that have an at least good knowledge of the English language. They could easily read the English documentation, but prefer to read it in their native language.
2. Readers who have basic English skills, but need an introduction into a new topic in their native language.
3. People who are not able to read English documents.

I think we should then focus on the second group for translated documentations (we simply cannot manage to translate everything non-english speakers would need and they are eventually lost at all when it comes to third-party libraries I fear). If we can satisfy their needs, we'll be at a good level.

So, what do these people need? I think @gregquat has a point here when talking about the quick tour and the book. If it is possible to keep both up-to-date, people will at least have a great start into the framework in their native language and can then, with some basic knowledge, move to more advanced topics.

The only thing I am worried about is that people who don't want to use the full-stack framework can't start with an introduction into the components in their native language. They would either have to start with a translated book (and therefore read a lot of things they don't need) or they have to start with the English documentation.

[gregquat]

I'm quite agree with that. We should also consider the number of unique visitors on the French and Italian parts of Symfony.com
I can keep the Book and the Quick Tour up to date as these parts do not move a lot. As @xabbuh said, it's enough for a beginner to start with the framework.

For the ones who do not want to use the full stack framework, we can suppose they are not noobs in development and so, we can suppose they can read and understand English.

What do you think?

[xabbuh]

For the one who do not want to use the full stack framework, we can suppose they are not noobs in developement and so, we can suppose they can read and understand English.

That's a fair point.

FYI, in #4171 I raised the question if we really need more than one version of the quick tour (afaics they only differ in the version used in the installation description).

[fabpot]

Stupid question: For which languages Google translate (http://translate.google.com/manager/website/?hl=en) does a good job at translating our docs? I've just tried on a couple of pages, and the automatic French translation is ok (far from perfect, but definitely understandable).

[cordoval]

spanish is the same level understandable

[xabbuh]

Same with German. The main problem is that the Google translator tries to translate PHP keywords, class names, etc. which makes it harder to read than it could have been.

[javiereguiluz]

@xabbuh you can prevent Google Translate from translating certain sections. In our case this would be as easy as adding class="notranslate" to code listings.

[gregquat]

That's what I was going to say. We could use the API to tell which sections and words Google Translation should ignore. But there may be some use restriction...

[xabbuh]

@javiereguiluz Nice, this might improve translations a lot.

[DIOHz0r]

I know a lot of programmers that don't know English (only spanish) and struggle them to understand the documentation (bad interpreting). I agree that is a hard work but if you check almost all program languages and big projects (GNU, Debian, PHP, CakePHP, etc) have "official not updated translations" to help those kind of persons.

gitnacho/symfony-docs-es is really outdated and @javiereguiluz has done a amazing work publishing a translate version of symfony 2.4 documentation but it isn´t refered at the official symfony.com website and it isn't published in github for contribute (as far as I know).

Not accepting the options of translations for me is really excluding. lt's like to everyone here go to China and try to read without know the native language and no english helper.

[Alsatian67]

Why don't you simply disable the merging of older branches in newer branches for translated docs ?
-> So long nobody has translated it for the new version, there is no translated page ...

[xabbuh]

The meeting is done by the translators in their repository. The only decision we can make is to not feature particular versions on symfony.com.

[garak]

Translations have been removed, so we can likely close this issue. Only action left is updating https://symfony.com/doc/master/contributing/documentation/translations.html

[xabbuh]

FYI, a blog post has also been published.

[xabbuh]

see #5744 for the documentation update