How can we help doc translators? #4078

Closed
wouterj opened this Issue Jul 31, 2014 · 22 comments

Comments

Projects
None yet
10 participants
@wouterj
Member

wouterj commented Jul 31, 2014

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

This comment has been minimized.

Show comment
Hide comment
@javiereguiluz

javiereguiluz Jul 31, 2014

Member

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?

Member

javiereguiluz commented Jul 31, 2014

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

This comment has been minimized.

Show comment
Hide comment
@gregquat

gregquat Aug 1, 2014

Contributor

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".

Contributor

gregquat commented Aug 1, 2014

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

This comment has been minimized.

Show comment
Hide comment
@ricardclau

ricardclau Aug 23, 2014

Contributor

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

Contributor

ricardclau commented Aug 23, 2014

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

This comment has been minimized.

Show comment
Hide comment
@fabpot

fabpot Aug 23, 2014

Member

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.

Member

fabpot commented Aug 23, 2014

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

This comment has been minimized.

Show comment
Hide comment
@fabpot

fabpot Aug 23, 2014

Member

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?

Member

fabpot commented Aug 23, 2014

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

This comment has been minimized.

Show comment
Hide comment
@garak

garak Aug 23, 2014

Contributor

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.

Contributor

garak commented Aug 23, 2014

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

This comment has been minimized.

Show comment
Hide comment
@gregquat

gregquat Aug 25, 2014

Contributor

@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?

Contributor

gregquat commented Aug 25, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@xabbuh

xabbuh Aug 25, 2014

Member

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.

Member

xabbuh commented Aug 25, 2014

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

This comment has been minimized.

Show comment
Hide comment
@gregquat

gregquat Aug 25, 2014

Contributor

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?

Contributor

gregquat commented Aug 25, 2014

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

This comment has been minimized.

Show comment
Hide comment
@xabbuh

xabbuh Aug 25, 2014

Member

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).

Member

xabbuh commented Aug 25, 2014

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

This comment has been minimized.

Show comment
Hide comment
@fabpot

fabpot Aug 25, 2014

Member

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).

Member

fabpot commented Aug 25, 2014

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

This comment has been minimized.

Show comment
Hide comment
@cordoval

cordoval Aug 25, 2014

Contributor

spanish is the same level understandable

Contributor

cordoval commented Aug 25, 2014

spanish is the same level understandable

@xabbuh

This comment has been minimized.

Show comment
Hide comment
@xabbuh

xabbuh Aug 25, 2014

Member

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.

Member

xabbuh commented Aug 25, 2014

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

This comment has been minimized.

Show comment
Hide comment
@javiereguiluz

javiereguiluz Aug 25, 2014

Member

@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.

Member

javiereguiluz commented Aug 25, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@gregquat

gregquat Aug 25, 2014

Contributor

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...

Contributor

gregquat commented Aug 25, 2014

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

This comment has been minimized.

Show comment
Hide comment
@xabbuh

xabbuh Aug 25, 2014

Member

@javiereguiluz Nice, this might improve translations a lot.

Member

xabbuh commented Aug 25, 2014

@javiereguiluz Nice, this might improve translations a lot.

@DIOHz0r

This comment has been minimized.

Show comment
Hide comment
@DIOHz0r

DIOHz0r Sep 1, 2014

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.

DIOHz0r commented Sep 1, 2014

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

This comment has been minimized.

Show comment
Hide comment
@Alsatian67

Alsatian67 Jun 11, 2015

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 ...

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

This comment has been minimized.

Show comment
Hide comment
@xabbuh

xabbuh Jun 11, 2015

Member

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.

Member

xabbuh commented Jun 11, 2015

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

This comment has been minimized.

Show comment
Hide comment
@garak

garak Sep 30, 2015

Contributor

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

Contributor

garak commented Sep 30, 2015

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

This comment has been minimized.

Show comment
Hide comment
@xabbuh

This comment has been minimized.

Show comment
Hide comment
@xabbuh

xabbuh Oct 1, 2015

Member

see #5744 for the documentation update

Member

xabbuh commented Oct 1, 2015

see #5744 for the documentation update

xabbuh added a commit that referenced this issue Oct 9, 2015

minor #5744 translations have been removed from symfony.com (xabbuh)
This PR was merged into the 2.3 branch.

Discussion
----------

translations have been removed from symfony.com

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets | #4078

The old page will be kept for people following a deep link or a bookmark, but the actual content has been removed and is replaced with a link to [the blog article](http://symfony.com/blog/discontinuing-the-symfony-community-translations).

Commits
-------

b2e78a6 translations have been removed from symfony.com

@xabbuh xabbuh closed this Oct 18, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment