Review of the Docs translation processes #54

Open
opened 2026-06-30 07:14:14 +00:00 by pboy · 9 comments
Owner

As a reminder: We need to coordinate the translation process with the translation group, as soon as the migration to forge is completed. In the meantime, it is on hold.

As a _reminder_: We need to coordinate the translation process with the translation group, as soon as the migration to forge is completed. In the meantime, it is on hold.
Owner

As far as I am aware, a lot of this work has already started. It could be better documented, however? The best people to ask for information would be @jibecfed, @peartown, or @rffontenelle might be able to clarify in more detail.

As far as I am aware, a lot of this work has already started. It could be better documented, however? The best people to ask for information would be @jibecfed, @peartown, or @rffontenelle might be able to clarify in more detail.
Member

Hi there, first step is to read the docs created by peartown and darkano :p
https://docs.fedoraproject.org/en-US/localization/doc_l10n/
Does it helps?

A good place to communicate with our three Localization admins (peartown, rffontenelle & myself) is the #l10n:fedoraproject.org matrix channel

Hi there, first step is to read the docs created by peartown and darkano :p https://docs.fedoraproject.org/en-US/localization/doc_l10n/ Does it helps? A good place to communicate with our three Localization admins (peartown, rffontenelle & myself) is the #l10n:fedoraproject.org matrix channel
Author
Owner

As @jibecfed mentioned in another issue noted, it is "fine to start large translation workflow from a tooling point of view. Everything is up and ...".
So let's start it.

What are the next steps to take? E.g., there are Server docs or CoreOS docs which are perfectly fine.

I'm specifically interested in Server docs, I can select language 'de' at the top, but nothing happens. Same with CoreOS. And – a little bit of teasing – if I read Documentation Translation Workflow the German text supposed to come up, looks strange from a German point of view.

If I look into translated sources repository, many part of the docs are there, including text for other languages.

For some parts, e.g. Docs home page, translation basically works, at least to some extent, and with some violation of the page design.
For some parts the naming is strange, e.g. "master" instead of "main".

I guess, we need a working plan to improve the situation.

As @jibecfed mentioned in [another issue](https://forge.fedoraproject.org/docs/team-docs/issues/43#issuecomment-875366) noted, it is "fine to start large translation workflow from a tooling point of view. Everything is up and ...". So let's start it. What are the next steps to take? E.g., there are [Server docs](https://docs.fedoraproject.org/en-US/fedora-server/) or [CoreOS docs](https://docs.fedoraproject.org/en-US/fedora-coreos/) which are perfectly fine. I'm specifically interested in Server docs, I can select language 'de' at the top, but nothing happens. Same with CoreOS. And – a little bit of teasing – if I read [Documentation Translation Workflow](https://docs.fedoraproject.org/de/localization/doc_l10n/) the German text supposed to come up, looks strange from a German point of view. If I look into translated sources repository, many part of the docs are there, including text for other languages. For some parts, e.g. Docs home page, translation basically works, at least to some extent, and with some violation of the page design. For some parts the naming is strange, e.g. "master" instead of "main". I guess, we need a working plan to improve the situation.

@pboy The language list you see in the language switch doesn't necessarily mean that specific docs were translated. The language switch is generated by rebuild-site.py from all existing languages in translated-sources repository.

Fedora Server Docs in German is showing English texts because it was not translated yet. See fedora-docs-l10n-fedora-server translation project in Weblate and the fedora-server l10n repository. Please notice the fedora-server directory doesn't exist for German in translated-sources repository.

The 'master' or 'main' you mention is the version name set in the antora.yml file. If the doc maintainers set version=master, then that value is used in the l10n file path (e.g. po/master/nav.po), but if version=~ then it fallbacks to main.

Note: the Documentation Translation Workflow needs to be updated in several aspects. For instance, main is the default since docs/translations-scripts@dc2e0ac7a0, but this document still mentions 'master'.

@pboy The language list you see in the language switch doesn't necessarily mean that specific docs were translated. The language switch is generated by [rebuild-site.py][rebuild-site.py] from all existing languages in [translated-sources][translated-sources] repository. Fedora Server Docs in German is showing English texts because it was not translated yet. See [fedora-docs-l10n-fedora-server][fedora-docs-l10n-fedora-server] translation project in Weblate and the [fedora-server][fedora-server] l10n repository. Please notice the [fedora-server directory doesn't exist][dont-exist] for German in translated-sources repository. The 'master' or 'main' you mention is the version name set in the antora.yml file. If the doc maintainers set `version=master`, then that value is used in the l10n file path (e.g. `po/master/nav.po`), but if `version=~` then it fallbacks to `main`. Note: the Documentation Translation Workflow needs to be updated in several aspects. For instance, main is the default since https://forge.fedoraproject.org/docs/translations-scripts/commit/dc2e0ac7a09a9f6d220701aa50087b9aff6e169e, but this document still mentions 'master'. [rebuild-site.py]: https://forge.fedoraproject.org/docs/docs-fp-o/src/branch/prod/build-scripts/rebuild-site.py#L388-L393 [translated-sources]: https://forge.fedoraproject.org/docs/translated-sources [fedora-docs-l10n-fedora-server]: https://translate.fedoraproject.org/projects/fedora-docs-l10n-fedora-server/ [fedora-server]: https://forge.fedoraproject.org/localization-docs/fedora-server/src/branch/main [dont-exist]: https://forge.fedoraproject.org/docs/translated-sources/src/branch/master/de
Owner

@jibecfed wrote in #54 (comment):

Hi there, first step is to read the docs created by peartown and darkano :p https://docs.fedoraproject.org/en-US/localization/doc_l10n/ Does it helps?

I noticed the docs only describe how to do this on Pagure. 😕 We have reached the point where Pagure is completely offline now.

https://docs.fedoraproject.org/en-US/localization/doc_l10n/#_repository_creation

Are there are plans to update this documentation so more folks could help set up Fedora Docs repositories for translations?

@jibecfed wrote in https://forge.fedoraproject.org/docs/tickets/issues/54#issuecomment-875362: > Hi there, first step is to read the docs created by peartown and darkano :p https://docs.fedoraproject.org/en-US/localization/doc_l10n/ Does it helps? I noticed the docs only describe how to do this on Pagure. 😕 We have reached the point where Pagure is completely offline now. https://docs.fedoraproject.org/en-US/localization/doc_l10n/#_repository_creation Are there are plans to update this documentation so more folks could help set up Fedora Docs repositories for translations?

@jflory7 https://forge.fedoraproject.org/docs/translations-scripts#adding-a-new-repository

That page indeed needs to be updated. I'll try to work on it this weekend.

@jflory7 https://forge.fedoraproject.org/docs/translations-scripts#adding-a-new-repository That page indeed needs to be updated. I'll try to work on it this weekend.
Owner

@rffontenelle Thanks, that is super useful in the meantime! Getting it up onto the docs site would make sure it is easy to discover.

@pbokoc @hricky I am wondering whether the Antora modules -> topics migration could impact how localization gets done? It might not, but it is something we should look at closely when we make these changes, per #66.

@rffontenelle Thanks, that is super useful in the meantime! Getting it up onto the docs site would make sure it is easy to discover. @pbokoc @hricky I am wondering whether the Antora modules -> topics migration could impact how localization gets done? It might not, but it is something we should look at closely when we make these changes, per #66.
Owner

@jflory7 wrote in #54 (comment):

@pbokoc @hricky I am wondering whether the Antora modules -> topics migration could impact how localization gets done? It might not, but it is something we should look at closely when we make these changes, per #66.

Hopefully not - we won't be moving anything between repositories or changing filenames of source files, so on the translation side it should all stay the same.

@jflory7 wrote in https://forge.fedoraproject.org/docs/tickets/issues/54#issuecomment-1368211: > @pbokoc @hricky I am wondering whether the Antora modules -> topics migration could impact how localization gets done? It might not, but it is something we should look at closely when we make these changes, per #66. Hopefully not - we won't be moving anything between repositories or changing filenames of source files, so on the translation side it should all stay the same.
Owner

@pbokoc The challenge I have noticed is that every Antora module gets its own l10n repo. If we squash all modules down to a single module in the larger component, this might break the l10n pipeline. I was looking at this with a recent Localization Team ticket, localization/tickets#81 (comment), with @rffontenelle.

@pbokoc The challenge I have noticed is that every Antora module gets its own l10n repo. If we squash all modules down to a single module in the larger component, this might break the l10n pipeline. I was looking at this with a recent Localization Team ticket, https://forge.fedoraproject.org/localization/tickets/issues/81#issuecomment-1369062, with @rffontenelle.
Sign in to join this conversation.
No project
No assignees
5 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
docs/tickets#54
No description provided.