Postulo/postulo

Watch

Fork 0

Wiki in several languages: find out whether it can be done, and how, before any page is translated #352

New issue

Closed

opened 2026-10-01 10:34:02 +00:00 by tiagoagueda · 1 comment

tiagoagueda commented

2026-10-01 10:34:02 +00:00

Owner

Requested by the maintainer on 2026-10-01: assess the possibility of having the wiki in multiple languages. This is the question #345 leaves open in its second half; it is asked here on its own so that it is answered before anybody translates a page.

What is known

The wiki is a git repository of Markdown files (postulo.wiki): 23 pages, about 77,000 words, one _Sidebar.md, a few images under images/. A page's name is its file's name.
Forgejo's wiki has no notion of a page's language. There is no language switcher, no per-language sidebar, no fallback from a missing translation to the English page. Whatever is built has to be built out of page names and links, or outside the wiki.
The interface is translated through gettext catalogues with a draft flag for what no speaker has read (docs/TRANSLATING.md), and from 0.5.0 through Weblate as a round trip (#349). #302 decided that the in-app help is written as templates and translated through those catalogues, with the wiki pointing at the same text.

What to assess

Each option against the same questions.

Options

Inside the Forgejo wiki, by naming: a suffix or a prefix per language (Getting-started.fr, fr/Getting-started if the wiki serves subfolders), with a hand-kept sidebar per language or one sidebar that links to language index pages.
A documentation site built from the wiki repository (a static site generator with real language support), published beside the instance or with the releases, the Forgejo wiki staying as the English source.
The application carries the translated layer (#302's help drawer and tooltips), and the wiki stays English for operators and developers. Translating the wiki is then mostly not needed for the people who use an instance.
A mix: 3 for users, 1 or 2 for the pages a user reads before they have an instance (Home, Getting started, Installing).

Questions for each

Landing: how does a reader arrive in their language, and what do they see when a page has no translation (the English page, said to be English)?
Staleness: how is a translated page tied to the revision of its source, and what lists the pages whose source has moved since? A translated page that describes last year's interface is worse than an English one.
The translator's path: can Weblate carry it (Markdown as a component, by page or by paragraph), so that it is the same round trip as the strings (#349) and the same draft rule, or does it need a process of its own?
Cost: 77,000 words today, growing with #345, times the languages a release selects (#347). What is realistic by hand, by machine draft, and reviewed? Which pages first?
Links, search and images: do links between pages stay inside a language; does the wiki's search mix languages; are screenshots per language (the companion issue on screenshots asks for generated ones, which is what would make that affordable)?
Hosting and the commitments: nothing fetched from a third party, readable with scripts off, both themes, right to left for the languages that need it.

Deliverable

Not a translated wiki. A written answer:

the options compared against the questions above, with what was actually tried;
a trial of the preferred option on one page (Getting started, in French and Portuguese), far enough to see the landing, the fallback and the staleness check working;
a recommendation, recorded in docs/TRANSLATING.md and in #345, which then carries the work.

Done when

The comparison and the trial are written up on this issue (or a wiki page it links to), and the maintainer has chosen.
#345's second section names the chosen way instead of listing the choices.

Requested by the maintainer on 2026-10-01: **assess the possibility of having the wiki in multiple languages.** This is the question #345 leaves open in its second half; it is asked here on its own so that it is answered before anybody translates a page. ## What is known - The wiki is a git repository of Markdown files (`postulo.wiki`): 23 pages, about 77,000 words, one `_Sidebar.md`, a few images under `images/`. A page's name is its file's name. - **Forgejo's wiki has no notion of a page's language.** There is no language switcher, no per-language sidebar, no fallback from a missing translation to the English page. Whatever is built has to be built out of page names and links, or outside the wiki. - The interface is translated through gettext catalogues with a `draft` flag for what no speaker has read (`docs/TRANSLATING.md`), and from 0.5.0 through Weblate as a round trip (#349). #302 decided that the in-app help is written as templates and translated through those catalogues, with the wiki pointing at the same text. ## What to assess Each option against the same questions. **Options** 1. **Inside the Forgejo wiki**, by naming: a suffix or a prefix per language (`Getting-started.fr`, `fr/Getting-started` if the wiki serves subfolders), with a hand-kept sidebar per language or one sidebar that links to language index pages. 2. **A documentation site built from the wiki repository** (a static site generator with real language support), published beside the instance or with the releases, the Forgejo wiki staying as the English source. 3. **The application carries the translated layer** (#302's help drawer and tooltips), and the wiki stays English for operators and developers. Translating the wiki is then mostly not needed for the people who use an instance. 4. A mix: 3 for users, 1 or 2 for the pages a user reads before they have an instance (*Home*, *Getting started*, *Installing*). **Questions for each** - **Landing:** how does a reader arrive in their language, and what do they see when a page has no translation (the English page, said to be English)? - **Staleness:** how is a translated page tied to the revision of its source, and what lists the pages whose source has moved since? A translated page that describes last year's interface is worse than an English one. - **The translator's path:** can Weblate carry it (Markdown as a component, by page or by paragraph), so that it is the same round trip as the strings (#349) and the same `draft` rule, or does it need a process of its own? - **Cost:** 77,000 words today, growing with #345, times the languages a release selects (#347). What is realistic by hand, by machine draft, and reviewed? Which pages first? - **Links, search and images:** do links between pages stay inside a language; does the wiki's search mix languages; are screenshots per language (the companion issue on screenshots asks for generated ones, which is what would make that affordable)? - **Hosting and the commitments:** nothing fetched from a third party, readable with scripts off, both themes, right to left for the languages that need it. ## Deliverable Not a translated wiki. A written answer: - the options compared against the questions above, with what was actually tried; - **a trial of the preferred option on one page** (*Getting started*, in French and Portuguese), far enough to see the landing, the fallback and the staleness check working; - a recommendation, recorded in `docs/TRANSLATING.md` and in #345, which then carries the work. ## Done when - The comparison and the trial are written up on this issue (or a wiki page it links to), and the maintainer has chosen. - #345's second section names the chosen way instead of listing the choices.

tiagoagueda added this to the 0.6.0 milestone

2026-10-01 10:34:02 +00:00

tiagoagueda added the

documentation

internationalisation

enhancement

labels

2026-10-01 10:34:02 +00:00

tiagoagueda referenced this issue

2026-10-01 10:34:04 +00:00

Documentation: a fuller wiki for the people who use, run and extend Postulo, readable in more than English #345

tiagoagueda referenced this issue

2026-10-03 01:59:13 +00:00

Docker Compose at home: one deployment page for a homelab, and the drift between the compose files and the wiki #704

tiagoagueda referenced this issue

2026-10-03 01:59:14 +00:00

Translations are made in Weblate only: the rule, the documents that contradict it, and what a commit does with a string #706

tiagoagueda referenced this issue from a commit

2026-10-06 14:29:33 +00:00

Build the pre-install wiki pages into a static site in several languages

tiagoagueda referenced this issue

2026-10-31 03:04:21 +00:00

Wiki: nothing runs wiki_site.py stale --strict or builds the translated pages, so a moved English source is noticed only by hand #1147

tiagoagueda referenced this issue

2026-11-01 14:58:46 +00:00

Wiki in several languages: every page through Weblate, published at wiki.tiagoagueda.com #1215

tiagoagueda referenced this issue

2026-11-11 15:03:22 +00:00

Documentation: a fuller wiki for the people who use, run and extend Postulo, readable in more than English #345

tiagoagueda commented

2026-11-11 15:03:22 +00:00

Author

Owner

Checked against this issue's "Done when" on 2026-11-11, and closing it.

The comparison and the trial are written up, and the maintainer has chosen. docs/TRANSLATING.md ("The wiki in other languages") records the decision taken here, a mix: the in-app help through the catalogues, and a site built from the wiki repository for the pages read in other languages. #1215 then took it further on 2026-11-01 with the maintainer's decisions: the whole wiki, in stages, through Weblate, published at https://wiki.tiagoagueda.com. The trial this issue asked for is live there: Getting started in French and Portuguese, with the landing by browser language, the English fallback that says it is English, and the staleness rule (a changed paragraph needs review) all working.
#345 names the chosen way. Its second section still lists the options in its text, so a comment there now states what was chosen and points to #1215.

What is left is doing it, not assessing it, and that is #1215: the remaining stages of pages, the release gate for fr-FR and pt-PT, and keeping scripts/weblate.py away from the wiki-* components. docs/TRANSLATING.md still describes the first shape of the site (scripts/wiki_site.py, a few pages); bringing that section in line with the Zensical site belongs to #1215 as well.

🤖 Generated with Claude Code

Checked against this issue's "Done when" on 2026-11-11, and closing it. - **The comparison and the trial are written up, and the maintainer has chosen.** `docs/TRANSLATING.md` ("The wiki in other languages") records the decision taken here, a mix: the in-app help through the catalogues, and a site built from the wiki repository for the pages read in other languages. #1215 then took it further on 2026-11-01 with the maintainer's decisions: the whole wiki, in stages, through Weblate, published at https://wiki.tiagoagueda.com. The trial this issue asked for is live there: *Getting started* in French and Portuguese, with the landing by browser language, the English fallback that says it is English, and the staleness rule (a changed paragraph needs review) all working. - **#345 names the chosen way.** Its second section still lists the options in its text, so a comment there now states what was chosen and points to #1215. What is left is doing it, not assessing it, and that is #1215: the remaining stages of pages, the release gate for fr-FR and pt-PT, and keeping `scripts/weblate.py` away from the `wiki-*` components. `docs/TRANSLATING.md` still describes the first shape of the site (`scripts/wiki_site.py`, a few pages); bringing that section in line with the Zensical site belongs to #1215 as well. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

tiagoagueda closed this issue

2026-11-11 15:03:22 +00:00