Decision on the future of translations

[LordSimal]

[!IMPORTANT] EVERYONE is welcome to include their opinion about this topic!

Currently the main https://book.cakephp.org supports 5 languages: en, pt, es, ja, fr

But translating docs and especially keeping all the translations in sync has always been a difficult topic to deal with.

As we are currently in the process of converting from RST files (powered by Sphinx) to MD files (powered by VitePress) we'd like to get a feeling, on how the already existing translations should be handled.

For me, I see the following possible ways to go:

1. All current translations will be ported over, no matter how out of sync they are
2. Only certain translations in a "good state" (e.g. ja and pt) will be ported over
3. Only en will be ported over and we expect users to use e.g. their browser built in translation feature (or Google translate) to get a translated docs page.

If you think there are more possible ways to go please comment them down bellow.

[dereuromark]

Voted for "3" since 15 years :) Stick to that. Maintainability for any non-en never works out.

[josbeir]

I'm all in with @dereuromark on this one.

[ADmad]

Drop all translations, even the better maintained ones like ja are always lagging/incomplete!

[LordSimal]

Dropping all translations would also change the already existing URL structure, so we'd need to make sure, that any language specific URLs redirect to the english version.

Unless we of course keep the en in the URL even though we'd drop the languages.

[ravage84]

I would tend to option 2 if there is a team of contributors who can clearly express their intent of continuing (and at best even intensivy) their work on that translation.

Thus, I'd like to hear feedback from people who contributed to the pt, es, ja and/or fr translations in the past 5 years.

I specifically would love to hear from the people of @cakephp/docs-fr , @cakephp/docs-jp & @cakephp/docs-pt what they think.

Are there people who want to step up to officially join such a translation team in our community?

If we can't find find teams big enough to keep these translations maintained, I'm OK with option 1 since since auto-translation has improved over the last few years.

[ravage84]

Currently the main https://book.cakephp.org supports 5 languages: en, pt, es, ja, fr

But translating docs and especially keeping all the translations in sync has always been a difficult topic to deal with.

As we are currently in the process of converting from RST files (powered by Sphinx) to MD files (powered by VitePress) we'd like to get a feeling, on how the already existing translations should be handled.

For me, I see the following possible ways to go:

1. All current translations will be ported over, no matter how out of sync they are

2. Only certain translations in a "good state" (e.g. `ja` and `pt`) will be ported over

3. Only `en` will be ported over and we expect users to use e.g. their browser built in translation feature (or Google translate) to get a translated docs page.

I would tend to option 2 if there is a team of contributors who can clearly express their intent of continuing (and at best even intensivy) their work on that translation.

Thus, I'd like to hear feedback from people who contributed to the pt, es, ja and/or fr translations in the past 5 years:

@999samurai @adrienlz @ajibarra @alexdev4 @arakakieth @areveron @arhell @arodu @ashcolor @ashfun @aster @aurenstakada @bitdaw @cauancabral @chav170 @conafectomanu @cpierce @dype35 @e2yamazaki @eltociear @enviniom @felipevr @fernando-henrique-bling @flaviengr @flohdez @gabriellasso @gig-shogo-ishikura @gotoeveryone @havokinspiration @hgsgtk @humuhimi @issakujitsuk @itosho @josbeir @juanpbergues @junichirojp @jykaweston @katayamahide @kazmaarakaki @kromodoro @lsofi @marcomomo @matsugen73 @mnishig @motooka @mr-ijij @nash-beta @nmaya @nojimage @o-dlr-o

I'm sorry if I attributed anybody unrelated.

Are there people who want to step up to officially join such a translation team in our community?

If we can't find find teams big enough to keep these translations maintained, I'm OK with option 1 since since auto-translation has improved over the last few years.

[ravage84]

Currently the main https://book.cakephp.org supports 5 languages: en, pt, es, ja, fr

But translating docs and especially keeping all the translations in sync has always been a difficult topic to deal with.

As we are currently in the process of converting from RST files (powered by Sphinx) to MD files (powered by VitePress) we'd like to get a feeling, on how the already existing translations should be handled.

For me, I see the following possible ways to go:

1. All current translations will be ported over, no matter how out of sync they are

2. Only certain translations in a "good state" (e.g. `ja` and `pt`) will be ported over

3. Only `en` will be ported over and we expect users to use e.g. their browser built in translation feature (or Google translate) to get a translated docs page.

I would tend to option 2 if there is a team of contributors who can clearly express their intent of continuing (and at best even intensivy) their work on that translation.

Thus, I'd like to hear feedback from people who contributed to the pt, es, ja and/or fr translations in the past 5 years:

@oddmutou @okinaka @oppara @ragatti @raphaeldealmeida @reinaldoborin @ronaldcarucci @ryu022304 @sachiko-kame @si-arakaki @steinkel @t-toshiya @tamurayukio @tatsurou-yajima @tavaresgerson @thejoelinux @tomoya185-miyawaki @trylam @wideefr @xbirdfr @xpyoda @yama @yannickv @yeliparra @ykanazawa @zachee54 @ziwot

I'm sorry if I attributed anybody unrelated.

Are there people who want to step up to officially join such a translation team in our community?

If we can't find find teams big enough to keep these translations maintained, I'm OK with option 1 since since auto-translation has improved over the last few years.

[tavaresgerson]

I agree with the second option ("2. Only certain translations in a "good state" (e.g. ja and pt) will be ported over"), and I am available to review and translate into Portuguese (pt).

[Arhell]

I only did small PRs, sync code where there was no need to translate. Example https://github.com/cakephp/docs/pull/8089

[kromodoro]

I am regularly translating cakePHP version 5.x into PT, however, due to the link relationships in sphinx it was not feasible to upload the documents individually, so I am making a large batch of approximately 134 files, with an expected completion date of December 31, 2025.

I vote for 3

[felipevr]

I also agree with the second option ("2. Only certain translations in a "good state" (e.g. ja and pt) will be ported over"), and I am available to review and translate into Portuguese (pt) too.

Em qui., 18 de set. de 2025 às 07:53, Marc Würth @.***> escreveu:

ravage84 left a comment (cakephp/docs#8091) https://github.com/cakephp/docs/issues/8091#issuecomment-3307043021

Currently the main https://book.cakephp.org supports 5 languages: en, pt, es, ja, fr

But translating docs and especially keeping all the translations in sync has always been a difficult topic to deal with.

As we are currently in the process of converting from RST files (powered by Sphinx https://www.sphinx-doc.org/en/master/) to MD files (powered by VitePress https://vitepress.dev/) we'd like to get a feeling, on how the already existing translations should be handled.

For me, I see the following possible ways to go:

1. All current translations will be ported over, no matter how out of sync they are

2. Only certain translations in a "good state" (e.g. ja and pt) will be ported over

3. Only en will be ported over and we expect users to use e.g. their browser built in translation feature (or Google translate) to get a translated docs page.

I would tend to option 2 if there is a team of contributors who can clearly express their intent of continuing (and at best even intensivy) their work on that translation.

Thus, I'd like to hear feedback from people who contributed to the pt, es, ja and/or fr translations in the past 5 years:

@999Samurai https://github.com/999Samurai @AdrienLZ https://github.com/AdrienLZ @ajibarra https://github.com/ajibarra @AlexDev4 https://github.com/AlexDev4 @ArakakiEth https://github.com/ArakakiEth @AReveron https://github.com/AReveron @Arhell https://github.com/Arhell @arodu https://github.com/arodu @ashcolor https://github.com/ashcolor @ashfun https://github.com/ashfun @aster https://github.com/aster @aurenstakada https://github.com/aurenstakada @bitdaw https://github.com/bitdaw @CauanCabral https://github.com/CauanCabral @chav170 https://github.com/chav170 @ConAfectoManu https://github.com/ConAfectoManu @cpierce https://github.com/cpierce @dype35 https://github.com/dype35 @e2yamazaki https://github.com/e2yamazaki @eltociear https://github.com/eltociear @enviniom https://github.com/enviniom @felipevr https://github.com/felipevr @fernando-henrique-bling https://github.com/fernando-henrique-bling @FlavienGr https://github.com/FlavienGr @flohdez https://github.com/flohdez @GabrielLasso https://github.com/GabrielLasso @gig-shogo-ishikura https://github.com/gig-shogo-ishikura @gotoeveryone https://github.com/gotoeveryone @HavokInspiration https://github.com/HavokInspiration @hgsgtk https://github.com/hgsgtk @humuhimi https://github.com/humuhimi @issakujitsuk https://github.com/issakujitsuk @itosho https://github.com/itosho @josbeir https://github.com/josbeir @juanpbergues https://github.com/juanpbergues @junichirojp https://github.com/junichirojp @JykaWeston https://github.com/JykaWeston @katayamahide https://github.com/katayamahide @KazmaArakaki https://github.com/KazmaArakaki @kromodoro https://github.com/kromodoro @lsofi https://github.com/lsofi @MarcoMomo https://github.com/MarcoMomo @matsugen73 https://github.com/matsugen73 @mnishig https://github.com/mnishig @motooka https://github.com/motooka @mr-ijij https://github.com/mr-ijij @Nash-BETA https://github.com/Nash-BETA @nmaya https://github.com/nmaya @nojimage https://github.com/nojimage @o-dlr-o https://github.com/o-dlr-o

I'm sorry if I attributed anybody unrelated.

Are there people who want to step up to officially join such a translation team in our community?

If we can't find find teams big enough to keep these translations maintained, I'm OK with option 1 since since auto-translation has improved over the last few years.

— Reply to this email directly, view it on GitHub https://github.com/cakephp/docs/issues/8091#issuecomment-3307043021, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABY6RUAOZYPGANUHTJRFZL3TKMLJAVCNFSM6AAAAACG2XFL4OVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTGMBXGA2DGMBSGE . You are receiving this because you were mentioned.Message ID: @.***>

[zachee54]

I would tend to an half-way between options 2 and 3.

fr is now totally out of sync, remaining in its 3.x state (a pity !). The gap is so large that I should better restart from scratch. And it seems that I'm quite alone to worry about it for fr. To reduce this full-translation effort, one could start from an automatic translation, even with IA, only reviewed by a human.

Some can think that in such a case, en is sufficient on its own and would be zero-cost. However, keeping a french translation matters in order to expand CakePHP in France, where it's still widely and unjustly ignored (most of french developers learnt Symfony at school).

As another way, some sites like Joomla (hu...) use an advanced translation system. Languages are synced, so that as a sentence is modified in English, its translations are deprecated and appear in the new English version in the translated text until the modified sentence is translated again. This maintains both consistency across languages and internationalisation. If you had such a tool, translating would be a piece of... cake ;-)

Make your choice !

[ADmad]

However, keeping a french translation matters in order to expand CakePHP in France, where it's still widely and unjustly ignored (most of french developers learnt Symfony at school).

How is Symfony taught in schools? It too only has docs in English.

[ADmad]

Symfony and Laravel the two most popular frameworks only have docs in English. So surely English only docs isn't not much of a barrier in a framework's adoption.

[nojimage]

I would like to vote 2, but since I haven’t been able to contribute much to translations myself, I think option 3 might be more realistic.

However, I believe it is important that official documentation pages still appear in search results in each language. Even if they are machine-translated, it would be better to keep localized pages available, rather than having only English pages.

Thank you as always for maintaining the documentation!

[nojimage]

@ADmad In the case of Laravel, for example, the Japanese documentation has been translated and published by an individual (https://readouble.com/laravel/), and I feel it has contributed a lot to its adoption.

If the official documentation is only provided in English, unofficial community translation sites might naturally appear for each language.

That might also be a natural way for the community to grow.

[josbeir]

Instead of contributions, we could investigate the use of AI in a CI pipeline to keep translations in sync, if option 2 is viable.

That said, I'm on train 3 🚋 : there are enough ways to have a proper translation these days. The goal here is to improve overall documentation quality and professionalism. I'm afraid that official community-maintained docs are never going to work.

[ADmad]

If the official documentation is only provided in English, unofficial community translation sites might naturally appear for each language.

That's totally fine. The community can maintain the translations. I really don't want the official docs to have incomplete/outdated translations.

[enviniom]

Instead of contributions, we could investigate the use of AI in a CI pipeline to keep translations in sync, if option 2 is viable.

That said, I'm on train 3 🚋 : there are enough ways to have a proper translation these days. The goal here is to improve overall documentation quality and professionalism. I'm afraid that official community-maintained docs are never going to work.

I agree with this opinion. I can help review and improve the Spanish translation. If that's not an option right now, I vote for option 2 and believe Spanish shouldn't be migrated. I think it's better to start from scratch since it's not currently synchronized. I will use an AI to make the Spanish translation faster and more efficient, making any necessary corrections.

[zachee54]

The goal here is to improve overall documentation quality and professionalism. I'm afraid that official community-maintained docs are never going to work.

I'm afraid it's right. Nowadays, relying on the community to maintain official docs in various languages doesn't make sense. If not the wonderful tool I told about, better choose option 3 and concentrate on quality.

[steinkel]

I vote for option 3, then let the community explore ways to maintain a translated version (automated or manual) that we could endorse from the EN book itself.

If we keep multiple languages, I wonder if we could link an agent to watch for new PRs in English and provide translations, in that case we would need to review the AI generated content to ensure it makes sense.

I would volunteer to review the Spanish PRs.

[ziwot]

I know people reading only french doc and unaware of dependency injection, maybe because it's still specified as "experimental" so my vote go to 3 too. I wanted to contribute to for translation for other people, but I'm reading the english doc myself.

[junichirojp]

i vote 2. because in Japan, our mother language don't have alphabet characters. only we have 3 types of characters, "漢字", "ひらがな", "カタカナ". so the impact of "Official site x Japanese" is very big for our mind. its good effect for japanese developers. EX: imagine like you back to trip from Qaṭar World Cup, maybe you can feel comfortable on your country's airport because you are around with your characters and can read everything without any tools.

and i don't like non English docs are hosted by somebody.

1. uncontrollable problem this case is uncontrollable the official community. its happen for confused for beginner. when i started ruby on rails, official English site and non Official japanese site is big different(not meaning contents, i wanna mention layout or looklike). so i confused and quit reading because i can't distinguish what is correct/incorrect.

EN: https://rubyonrails.org/docs JP: https://railsguides.jp/getting_started.html

2. sustainability someone's passion is over someday. and the end is going to zombie.

like me, i started translate 2015 after NY, Cakephp3, this year i married. i translated with passion for few years, but it's hard to take time after 2019, my first baby was born. and second baby was born at 2021. and these days, i can't translate any more because my lifestyle was changed everything. so now i'm in zombie for translation.

if the official hosted translations, maybe somebody taking next baton at anytime as they like. i think, it's very important for easy contributing environment.

Anyway, i don't translate few years, i feel happy because someone take next baton. this is great case of Open Source, bye!

[rochamarcelo]

Will this new 'flow' create po files to help translate the documentation? If yes, I would go with option 2.

[josbeir]

Will this new 'flow' create po files to help translate the documentation? If yes, I would go with option 2.

No, gettext is not ment for content translations, only strings.

[cpierce]

I think I agree with @rochamarcelo

[markstory]

we could investigate the use of AI in a CI pipeline to keep translations in sync, if option 2 is viable.

Please no LLMs in CI.

[motooka]

I agree with the option 2, and I would like to suggest a similar option.

Let's imagine when the translations work well. IMO, the main outcome of translations would be "welcoming new users". They would want to know...

• What is CakePHP?
• How to install into my development environment?

Thus, I think translating only the following contents would be a cost-effective way:

• CakePHP at a Glance
• Quick Start Guide

If a new user gets interested in CakePHP, they will be happy to use their favourite translating tools.

[kevindecapite]

My vote is for option 3 (i.e. drop all non-English translations) because of the following:

1. Modern translation tools are sufficient to convey the intended meaning (we're not translating literature, but tech docs);
2. The preponderance and ubiquity of the English language;
3. CakePHP's relatively small community;
4. @ADmad's very salient points that larger communities aren't bothering with non-English docs.

Taking these 4 points together, it seems evident to me that the Cake community would be better served investing in continuously improving the English docs and other parts of the framework ecosystem rather than scatter our energy across this translation project that will likely bear little fruit.

[humuhimi]

I talked to some Japanese devs about this.They want keeping English as default but not completely dropping existing translations,even partial translation helps people like me to get started. Removing Japanese completely may be a missed opportunity for the community here I guess.

So somewhere between 2 and 3.