Derive localized /development pages from English sources

Rasam Hossainrequested to merge
rasamhossain/hide-contribute-pages into main

What does this MR do and why?

The docs site intentionally doesn't translate the Contribute (/development/) docs. Originally, we decided to copy all the development content with only front-matter intact for Japanese under this issue: MVC to hide "Contribute" pages and navigation in Japanese localized docs site. However, the with time, a lot of these development pages are constantly moved, deleted or more pages are created, so this initial MVC doesn't work anymore.

Additionally, English fallback mounts already exist for every locale in config/_default/hugo.yaml (the <<: *gitlab-en / *omnibus-en / *runner-en / *charts-en / *operator-en blocks. But those fallbacks were never actually reached. In module.mounts the locale mounts are listed before the English fallback mounts, and for a given target path the first mount that supplies a file wins. So any file in doc-locale/<locale>/development/ silently overrode the English source — and what lives there is 615 front-matter-only stub files across the 5 content repos: English titles, no translated body, no description.

Across the 636 English dev pages, that produced two different broken outcomes:

  • 515 pages had a stub. The stub won, so the page was built from stale placeholder front matter. development/contributing/_index.md's stub carried an outdated info: URL (docs.gitlab.com/ee/development/development_processes.html#…) and no description, so the page silently lost its meta description. Every new or renamed English dev page also required a hand-made matching stub.
  • 121 pages had no stub. These fell through to the English fallback and rendered the full English body under a /ja-jp/ URL — untranslated English prose in Japanese chrome, indexed by search.

So the fallback mechanism was technically already correct but working partially; it was being shadowed by files that contributed nothing but maintenance burden. This MR excludes them so localized /development pages are fully derived from English sources at build time, with zero stub maintenance.

What changed:

  • config/_default/hugo.yaml — for ja-jp, fr-fr, and ko-kr, added files: ['! development/**'] to the gitlab, omnibus-gitlab, gitlab-runner, and charts-gitlab locale mounts. On gitlab-operator, replaced '! developer/adr/*' with '! developer/**' and kept '! adr/*', since its dev docs live under developer/. English mounts and the fallback blocks are untouched.
  • themes/gitlab-docs/layouts/_partials/page-content.html — a new $isLocalizedDevDoc becomes the first branch of the main content chain so .Content is skipped, adds data-pagefind-ignore="all" to the content wrapper, and hides the right-side TOC. The contribution disclaimer replaces the body.

One important thing to note: $isLocalizedDevDoc also requires the locale to have contribution-disclaimer data. contribution-disclaimer.html renders nothing when data/<lang>/contribution-disclaimer.yaml is missing, and only en-us and ja-jp have it — so suppressing the body for any non-default language would give fr-fr/ko-kr dev pages a title and nothing else once those locales are enabled. With the check they keep serving the English body and switch over automatically when their disclaimer data lands. Confirmed byte-identical output for ja-jp. As a result, for now, if we'd like to test this with korean and french, we'd not be able produce the correct output. Hence, the testing should be only limited to japanese only.

Related

Screenshots, screen recordings, or links to review app

Virtually the user level behaviour doesn't change. So the before and after is pretty identical. The current MR removes the technical debt of having to maintain hundreds of japanese development files, which is not needed at all.

How to set up and validate locally

Initial validation:

  1. Configure a local GitLab Docs environment.
  2. Check out this branch.
  3. Update the sibling content repos so they're current: make update-all-projects.
  4. Confirm the ja-jp stubs are still present, for example ../gitlab/doc-locale/ja-jp/development/contributing/_index.md.
  5. Run make view.
  6. Open /ja-jp/development/contributing/ — expect the English title and the Japanese disclaimer with a working link to the English page, no body, and no right-side TOC.
  7. View source and confirm <meta name="description" content="Code contribution guidelines, style guides, and processes.">. That string exists only in the English file; the stub has no description, so its presence proves the stub was bypassed.
  8. Open one of the /development pages e.g., /ja-jp/development/secure_coding_guidelines/ — a page with no ja-jp stub, to confirm the English fallback still supplies pages that were never stubbed.
  9. Open /development/contributing/ and confirm the English page is unchanged.

Verified locally with Hugo 0.154.5: full build exits 0 with zero errors, 636 ja-jp dev pages match 636 en-us, suppressed bodies measure 1 character against 48,633 in English, data-pagefind-ignore="all" appears on localized dev pages only, and English /development/ output is byte-identical to a pre-change build. A --environment translation build confirms fr-fr/ko-kr keep English bodies rather than rendering blank.

Secondary validation:

  1. Now delete all the development files from one of the repo. e.g., go to your GitLab monorepo locally and delete the /doc-locale/ja-jp/development directory completely,
  2. Rebuild the docs site (should be automatic), and check if the development pages still render the correct english title and japanese disclaimer content body.

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

  • I have evaluated the MR acceptance checklist for this merge request.
  • If this MR changes how markdown is interpreted, share this MR in the #tech-docs-localization slack channel. The translation tooling might need to be updated, for example if new syntax is added or existing syntax rendering is changed.

Merge request reports