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 #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) <#8091 (comment)> 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 <#8091 (comment)>, 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 !