RFC 3.0 - Change in Concept for Docs Translations

[ravage84]

In recent times we've had quite a few starts of translations or better said translation attempts.
As I've mentioned before I'm not a big fan of them because of reasons I've also stated before.

Though I do see some need and some use to some certain translations.

But as the past has proven, we have yet to see an up to date and 100 % covered translation of the docs in any language.
Since I don't believe we will ever achieve that without trying to greatly mobilize our community for that cause, I would like to propose a (little) change in concept when it comes to docs translations.

So let's answer why should we have translations of the docs in various languages?
I think the most compelling reason is to attract developers which aren't strong in English to our Community and our Framework, by easing up their first steps.

Those first steps are in my opinion (translated into the current book chapters and pages)

• Welcome
• Basic Instalation and requirements (does not need to cover the advanced installations, but URL rewriting)
• Getting Started
• Blog Tutorial
• CakePHP Overview
  • Wat is CakePHP, Why use it?
  • Understanding MVC
  • Where to get help?

Those chapters and pages make sure a developer will

• understand the basics of the framework
• and have a working installation.

Beyond that, I believe we can neglect the translations.
This will help to prevent the translations become outdated because the content of the pages mentioned above is not changed as much as the rest of the docs.

Simply said:
Let's consolidate all the pages that a developer needs to understand the basics of the framework and have a working installation into a first "act" of the book and only allow translations of this act.

Since we have to change how the book is structured, this RFC is headed towards 3.0 and not 2.0.

[ravage84]

As an alternative or amendment to this idea, I could envision a two level system where we have basic and full translations.

Basic means what is described above and full means the translations attempts to translate all content (we could define sone exceptions though).

This way, we could allow translations such as the french to attept to cover the full translations since we know we have a community and motivated people behind it.

[markstory]

Perhaps we can use the intro sections as a minimum for a translation? Let new translations be created without the full content, but if a translation isn't able to get at least that much content translated in X time it can/should be removed. This might be a terrible idea though.

[ravage84]

The idea is not so terrible, as the stale sr and ro translations (2.x, though) sadly show...

[cake17]

I agree with the fact that new translations should at least contain the intro section and more precisely:

• Preface (maybe without 3.0-migration-guide)
• Getting Start (and maybe just installation and configuration)

These parts almost never change so it can be a good start for beginners.

Technically, we could maybe create a branch for people who ask to translate (example: 3.0-vi) and tell them that it will be merged only if it contains the parts mentionned above. Like this, it doesn't create non-complete language version, but let people work on these branches. And we'll easily see if the community for a language is enough active or if it can be deleted (after a long while)

I don't know enough sphinx to know if it's possible to make references to english version each time the language version is not present. This would avoid to duplicate the english libraries files from language to language (with the problem of updating the languages versions when english version change).

[andre-pdassis]

I do agree on intro sections being a base for new languages too. I am focusing on the main sections first. And there will be a long work ahead. Today, here in Brazil, there is a lazy habit about other languages. Even the bigger Facebook CakePHP brazilian community does not accept any non-portuguese content. It is a little hard to penetrate in such politics. I am thinking if it is a good idea to create some group references in the docs for each language to ease recruiting tasks.

[cake17]

@andtxr we add the french community website on this page. If there is a reference website, maybe the portuguese community can add it there.
I'm happy to see other languages translated :)

[cake17]

I might have a temporary solution for partial translations.

I'm wondering if we could just keep the same tree folders and files up to date with the en version.

Then for untranslated files, we put a message on the page, something like this (I'll take the example of a spanish page):

The documentation is not currently supported in es language for this page.
Please feel free to send us a pull request on [github](https://github.com/cakephp/docs).
You can referer to the english version to have information about this page's topic.

We would only put this message and no english version below. This means:

• no need to keep it up to date each time the english version changes
• People who want to translate don't have to create the files as we maintain the structure of folders & files for all languages (not really tiresome as it does not change every week).
• no errors when building with sphinx, no wrong links because all the pages exist
• This also encourages people to use "Improve Docs" as all pages are created. (Just need to copy paste english version)
• and best of all, no depreciated version (no old page not up-to-date).

I will do this for es version, let me know what you think of this.

[cake17]

After working on es files, just a reminder here to avoid sphinx issues: needs to include all the toc.

Otherwise, I think it can be a solution to the unmaintained translations.

So things to keep in mind when english version is modified:

• If a file is added or the structure of folders is changed, we would change it for all languages (and replace the content by the note message explaining how to help translate the file)
• If toc are edited in en version, also edit them in other languages