Time to publish the Polish translation?

Mailing Lists php.doc
1

First, my apologies for having incorrectly disabled the doc-pl@lists.php.net mailing list a couple of months ago when we cleaned up inactive mailing lists. I had incorrectly identified the Polish translation efforts as having gone dormant.

We don't have any guidelines on what constitutes an active translation, which is maybe a discussion we should have on the phpdoc@lists.php.net list, but according to the translation status (PHP: Documentation Tools), it looks like about 9% of the Polish translation is up to date. This is already more than a couple of other languages that are currently active on PHP.net.

Does anyone object to me flipping the switch and making the Polish translation active?

Thanks.

Jim

2

Hi,

For consider a translation active, tow parameters must be reeded:

1) the translation rate.
2) the translation activity.

The problem it’s to define the limit.

No objection to activate the pl translation.

Jean-Baptiste

Le 25 oct. 2024 à 02:04, Jim Winstead <jimw@trainedmonkey.com> a écrit :

First, my apologies for having incorrectly disabled the doc-pl@lists.php.net mailing list a couple of months ago when we cleaned up inactive mailing lists. I had incorrectly identified the Polish translation efforts as having gone dormant.

We don't have any guidelines on what constitutes an active translation, which is maybe a discussion we should have on the phpdoc@lists.php.net list, but according to the translation status (PHP: Documentation Tools), it looks like about 9% of the Polish translation is up to date. This is already more than a couple of other languages that are currently active on PHP.net.

Does anyone object to me flipping the switch and making the Polish translation active?

Thanks.

Jim

3

[Sending it again, as apparently I completely forgot how to send to
mailing lists...]

Hi Jim,

W dniu 25.10.2024 o 02:02, Jim Winstead pisze:

First, my apologies for having incorrectly disabled the doc-pl@lists.php.net mailing list a couple of months ago when we cleaned up inactive mailing lists. I had incorrectly identified the Polish translation efforts as having gone dormant.

no worries , mistakes happen, especially when one is doing a lot.
Thanks for the good effort, I was observing your contributions to many
php.net systems and I'm glad you are still contributing. There was
something cool to see the creator of news.php.net coming back to
casually add some more improvements 23 years later :smiley:

We don't have any guidelines on what constitutes an active translation, which is maybe a discussion we should have on the phpdoc@lists.php.net list, but according to the translation status (PHP: Documentation Tools), it looks like about 9% of the Polish translation is up to date. This is already more than a couple of other languages that are currently active on PHP.net.

Does anyone object to me flipping the switch and making the Polish translation active?

Going back to the main topic, personally getting the Polish
documentation enabled was obviously my goal (for many years :D),
and it actually did get enabled for a moment by Gina.

However, I asked her to temporarily revert the flag flip as it was
just after I caught up to ~4 years of outdated files and I simply
wanted to ensure more decent quality before we make it available.

Back then I opened this PR Revert "Enable Polish translation again", for now by Sobak · Pull Request #989 · php/web-php · GitHub
where I included a "todo" for myself and the other Polish manual
contributor. Having reviewed it today, I must say that actually
I could tick off most of the boxes.

The only one left is related to (I believe) some infrastructure bug,
where upon enabling the Polish language appears on the list but it leads
to 404 page. I believe the language was enabled long enough for the docs
to be built, but it's been some time ago and now I'm not 100% sure.

All in all, I guess it's just a matter of making a call. On one hand I'd
like to make the translation even better and more complete (infinite
beta syndrome?), on the other hand I see no reason to not enable it.

Thanks,
Maciej.

Thanks.

Jim

PS: On a different note, does anyone know the correct e-mail address to
subscribe to the php.doc.pl list?

4

On Thu, Oct 24, 2024 at 9:03 PM Jim Winstead <jimw@trainedmonkey.com> wrote:

First, my apologies for having incorrectly disabled the doc-pl@lists.php.net mailing list a couple of months ago when we cleaned up inactive mailing lists. I had incorrectly identified the Polish translation efforts as having gone dormant.

Incidentally, I may ask you to check the pt_BR maillist? Its commit’s trigger stopped sending mails a while ago, so the very small Portuguese community it’s at loss of actively reviewing all commits.

We don’t have any guidelines on what constitutes an active translation, which is maybe a discussion we should have on the phpdoc@lists.php.net list, but according to the translation status (https://doc.php.net/revcheck.php?lang=pl), it looks like about 9% of the Polish translation is up to date. This is already more than a couple of other languages that are currently active on PHP.net.

I would argue about issuing two different guidelines, instead of one. One guideline for enabling, and another for disabling. For enabling, the translation compilation must be ok and has all files on chapters/ and language/ translated (instead of a percentual). And for disabling, for having the manual build failing or no commits for 3 months.

Beyond chapters/ and language/, maybe faq/ and security/ may be included, but any inclusion may further hinder any nascent new language translation.

André L F S Bacci

5

On Sat, Oct 26, 2024 at 10:03 AM Maciej Sobaczewski <msobaczewski@gmail.com> wrote:

The only one left is related to (I believe) some infrastructure bug,
where upon enabling the Polish language appears on the list but it leads
to 404 page. I believe the language was enabled long enough for the docs
to be built, but it’s been some time ago and now I’m not 100% sure.

This is a symptom of an old issue. The definition list of “what is an active, building, publishable” translation is spread in various files, in various formats, in various repositories.

Running
grep -ri --exclude-dir={.svn,.git} --color pt_BR .
on a fresh checkout of doc-base reveal various places inside one repo.

This may be the time to erase all duplications, in all repositories in favor of a unique file, and then make doc-base/configure.php generate various formats that these instances can local import or are replaced from .dist files, or download from building machines, if in other repositories.

André

6

On Sat, Oct 26, 2024, at 8:20 AM, André L F S Bacci wrote:

On Thu, Oct 24, 2024 at 9:03 PM Jim Winstead <jimw@trainedmonkey.com> wrote:

First, my apologies for having incorrectly disabled the doc-pl@lists.php.net mailing list a couple of months ago when we cleaned up inactive mailing lists. I had incorrectly identified the Polish translation efforts as having gone dormant.

Incidentally, I may ask you to check the pt_BR maillist? Its commit's trigger stopped sending mails a while ago, so the very small Portuguese community it's at loss of actively reviewing all commits.

I don't see anything abnormal in the list setup, but it looks to me like none of the language lists are getting commit messages and haven't for years, maybe since the switchover to Git from SVN?

We don't have any guidelines on what constitutes an active translation, which is maybe a discussion we should have on the phpdoc@lists.php.net list, but according to the translation status (PHP: Documentation Tools), it looks like about 9% of the Polish translation is up to date. This is already more than a couple of other languages that are currently active on PHP.net.

I would argue about issuing two different guidelines, instead of one. One guideline for enabling, and another for disabling. For enabling, the translation compilation must be ok and has all files on chapters/ and language/ translated (instead of a percentual). And for disabling, for having the manual build failing or no commits for 3 months.

Beyond chapters/ and language/, maybe faq/ and security/ may be included, but any inclusion may further hinder any nascent new language translation.

Yes, I think different enabling and disabling guidelines are a good idea and your enabling proposal is in line with what I was thinking and had discussed with Gina on IRC. I would want to include security because it helps emphasize that it is an important part of the documentation.

Jim

7

On Sat, Oct 26, 2024, at 10:31 AM, André L F S Bacci wrote:

On Sat, Oct 26, 2024 at 10:03 AM Maciej Sobaczewski <msobaczewski@gmail.com> wrote:

The only one left is related to (I believe) some infrastructure bug,
where upon enabling the Polish language appears on the list but it leads
to 404 page. I believe the language was enabled long enough for the docs
to be built, but it's been some time ago and now I'm not 100% sure.

This is a symptom of an old issue. The definition list of "what is an active, building, publishable" translation is spread in various files, in various formats, in various repositories.

Running
grep -ri --exclude-dir={.svn,.git} --color pt_BR .
on a fresh checkout of doc-base reveal various places inside one repo.

This may be the time to erase all duplications, in all repositories in favor of a unique file, and then make doc-base/configure.php generate various formats that these instances can local import or are replaced from .dist files, or download from building machines, if in other repositories.

Looking at those results, it looks like they're all either related to CHM building or QA scripts.

The building and publishing of the web version of the documentation (and non-CHM downloads) are all controlled by a script in the https://github.com/php/systems repository (specifically `build-docs-rsync`) that gets the list of active languages from the `include/languages.inc` file in GitHub - php/web-php: The www.php.net site

So I think we can just move Polish to the active languages list in `include/languages.inc` and debug from there if it doesn't just work.

The way the CHM files are built is not totally automated right now, so I don't think we need to worry too much about it until that changes.

More medium term, I think the list of active languages should be moved to `doc-base` instead of `web-php` so the documentation team has direct control over it.

Jim

8

We don't have any guidelines on what constitutes an active translation, which is maybe a discussion we should have on the phpdoc@lists.php.net list,

I would argue about issuing two different guidelines, instead of one. One guideline for enabling, and another for disabling. For enabling, the translation compilation must be ok and has all files on chapters/ and language/ translated (instead of a percentual). And for disabling, for having the manual build failing or no commits for 3 months.

Beyond chapters/ and language/, maybe faq/ and security/ may be included, but any inclusion may further hinder any nascent new language translation.

Yes, I think different enabling and disabling guidelines are a good idea and your enabling proposal is in line with what I was thinking and had discussed with Gina on IRC. I would want to include security because it helps emphasize that it is an important part of the documentation.

With a new request for a new language[1], this may be the time to
address this discussion, to create an `doc-base/docs/new-language.md`
filr, or an entry on `doc-base/docs/faq.md`. Or perhaps both.

André

[1] Translate Docs into Hindi Language · Issue #177 · php/doc-base · GitHub

9

On Sat, Oct 26, 2024, at 8:20 AM, André L F S Bacci wrote:

On Thu, Oct 24, 2024 at 9:03 PM Jim Winstead <jimw@trainedmonkey.com> wrote:
Incidentally, I may ask you to check the pt_BR maillist? Its commit's trigger stopped sending mails a while ago, so the very small Portuguese community it's at loss of actively reviewing all commits.

I don't see anything abnormal in the list setup, but it looks to me like none of the language lists are getting commit messages and haven't for years, maybe since the switchover to Git from SVN?

php.doc.cvs mailing list shows that en (and doc-base)
keeps this functionality, so this may facilitate finding where the
change is necessary to restore triggered list posting for pt_BR (or
all) languages.

André L F S Bacci

10

On Mon, Nov 11, 2024, at 11:52 AM, André L F S Bacci wrote:

On Sat, Oct 26, 2024, at 8:20 AM, André L F S Bacci wrote:

On Thu, Oct 24, 2024 at 9:03 PM Jim Winstead <jimw@trainedmonkey.com> wrote:
Incidentally, I may ask you to check the pt_BR maillist? Its commit's trigger stopped sending mails a while ago, so the very small Portuguese community it's at loss of actively reviewing all commits.

I don't see anything abnormal in the list setup, but it looks to me like none of the language lists are getting commit messages and haven't for years, maybe since the switchover to Git from SVN?

php.doc.cvs mailing list shows that en (and doc-base)
keeps this functionality, so this may facilitate finding where the
change is necessary to restore triggered list posting for pt_BR (or
all) languages.

My preference would be to not send commit/PR/issue messages to the mailing lists and instead document how people can sign up to them through GitHub itself. I believe that sending them to the mailing lists drowns out conversation and clutters the archives for little gain.

Jim

11

On Sat, Nov 16, 2024 at 4:49 PM Jim Winstead <jimw@trainedmonkey.com> wrote:

My preference would be to not send commit/PR/issue messages to the mailing lists and instead document how people can sign up to them through GitHub itself. I believe that sending them to the mailing lists drowns out conversation and clutters the archives for little gain.

In general, yes. But note that discussions moved almost entirely outside the mailing lists (as observed from https://news-web.php.net/php.doc and other language list mirrors), so updating some languages to be mixed use is not a great loss.

Perhaps, having separated php-lang and php-lang-vcs maillists is the way ahead. So human conversations would occur at php-lang, and commits would be mirrored at php-lang-vcs.

André L S S Bacci