Initial i18n support #793

cdn0x12 commented 2026年05月21日 00:32:49 +02:00

This PR uses Eleventy's built-in EleventyI18nPlugin to add initial i18n support to Codeberg Documentation.

closes #136

The main changes are as follows:

1. Now we use content.11tydata.mjs instead of content.11tydata.json as content config to automatically calculate translation keys based on page paths.
2. Existing docs don't have language tags. To avoid breaking URLs (from /<slug> to /en/<slug>), I kept existing docs in their original locations relative to content. However, managing various translations directly under content/ would clutter the directory. So, I'll centralize all translations into a separate content/l10n/ folder. Therefore I customized the permalink logic in content/l10n/l10n.11tydata.mjs to strip the /l10n/ prefix from the final URLs.
3. Moved template strings to content/_data/i18n.json. Templates now use {{ i18nDict.<string_key> }} to insert text. Some strings include links or <kbd> tags. Considering that:
   a. Splitting them into segments makes translation difficult due to different word orders in different languages.
   b. Leaving them as-is means every translation must maintain its own copy of links, which leads to inconsistency.
   Therefore, I added a tReplace filter. See content/_includes/contribution_invitation.njk and content/_data/i18n.json for how it’s used.
4. Added language switcher button. See content/_includes/language_switcher.njk

Notes

1. Currently, all articles still link to versions without language tags. Manually adding tags to every link in translated docs is prone to errors. I think it would be better to try to implement logic that automatically adds the language prefix during navigation based on whether a translation exists.
2. As mentioned in #136 (comment) , we need to add warnings for outdated translations. We might also need other notices, like incomplete translation incomplete.
3. I haven't added instructions on how to add or maintain translations yet. If this PR is acceptable, I’ll add them in a follow-up PR.
4. This PR does not include any additional i18n content, so theoretically, no styling changes appears so far. If this PR is acceptable, I'd like to add(and maintain) full Simplified Chinese documentation as an example in a follow-up PR.
5. We should also try matching the user's language to provide prompts or auto-redirect them to the documentation in their preferred language.
6. We also need to make sure PageFind works properly. I haven't tested it yet.

This PR uses Eleventy's built-in EleventyI18nPlugin to add initial i18n support to Codeberg Documentation. closes #136 The main changes are as follows: 1. Now we use `content.11tydata.mjs` instead of `content.11tydata.json` as content config to automatically calculate translation keys based on page paths. 2. Existing docs don't have language tags. To avoid breaking URLs (from `/<slug>` to `/en/<slug>`), I kept existing docs in their original locations relative to `content`. However, managing various translations directly under `content/` would clutter the directory. So, I'll centralize all translations into a separate `content/l10n/` folder. Therefore I customized the permalink logic in `content/l10n/l10n.11tydata.mjs` to strip the `/l10n/` prefix from the final URLs. 3. Moved template strings to `content/_data/i18n.json`. Templates now use `{{ i18nDict.<string_key> }}` to insert text. Some strings include links or `<kbd>` tags. Considering that: a. Splitting them into segments makes translation difficult due to different word orders in different languages. b. Leaving them as-is means every translation must maintain its own copy of links, which leads to inconsistency. Therefore, I added a `tReplace` filter. See `content/_includes/contribution_invitation.njk` and `content/_data/i18n.json` for how it’s used. 4. Added language switcher button. See `content/_includes/language_switcher.njk` ## Notes 1. Currently, all articles still link to versions without language tags. Manually adding tags to every link in translated docs is prone to errors. I think it would be better to try to implement logic that automatically adds the language prefix during navigation based on whether a translation exists. 2. As mentioned in https://codeberg.org/Codeberg/Documentation/issues/136#issuecomment-6817474 , we need to add warnings for outdated translations. We might also need other notices, like incomplete translation incomplete. 3. I haven't added instructions on how to add or maintain translations yet. If this PR is acceptable, I’ll add them in a follow-up PR. 4. This PR does not include any additional i18n content, so theoretically, no styling changes appears so far. If this PR is acceptable, I'd like to add(and maintain) full Simplified Chinese documentation as an example in a follow-up PR. 5. We should also try matching the user's language to provide prompts or auto-redirect them to the documentation in their preferred language. 6. We also need to make sure PageFind works properly. I haven't tested it yet.

mahlzahn commented 2026年06月25日 15:29:29 +02:00

I am still unsure if this is really worth the effort, but I like how Weblate does it for their own documentation translation.

1. Have original English documentation in rst files (we md, fine, too).
2. Split these in small paragraphs for translators
3. Render the page with translated paragraphs for a given language, but only if not outdated, else render English original paragraphs.

Thus, never outdated documentation is shown, only sometimes English parts instead of translated.

I am still unsure if this is really worth the effort, but I like how Weblate does it for their own documentation translation. 1. Have original English documentation in rst files (we md, fine, too). 2. Split these in small paragraphs for translators 3. Render the page with translated paragraphs for a given language, but only if not outdated, else render English original paragraphs. Thus, never outdated documentation is shown, only sometimes English parts instead of translated.

cdn0x12 commented 2026年06月25日 15:56:36 +02:00

In my point of view, breaking the article into segments loses the overall context (for translators). Plus, reading a half-translated article could be a worse experience than reading one that hasn't been translated at all. If it's left untranslated, readers could just use their preferred tools to translate the entire page.

For now this PR is just about adding multi-language support itself, not covering the translation workflow. These changes should still be useful if we decide to integrate with Weblate in the future.

In my point of view, breaking the article into segments loses the overall context (for translators). Plus, reading a half-translated article could be a worse experience than reading one that hasn't been translated at all. If it's left untranslated, readers could just use their preferred tools to translate the entire page. For now this PR is just about adding multi-language support itself, not covering the translation workflow. These changes should still be useful if we decide to integrate with Weblate in the future.

Some required checks are missing.

You are not authorized to merge this pull request.