Mark UI text with shortcodes and validate it against gitlab.pot

Marcel Amiraultrequested to merge
poc-ui-text-shortcode into master

What this does

We currently mark UI text in the docs with Markdown bold, but bold is overloaded: people keep using it for emphasis (despite the our guidance to avoid it), and we also use it for UI text from other products. Translation tooling looks up UI strings in locale/gitlab.pot to reuse an already-translated string, and it has no way to tell which bold text is an actual GitLab label, or if missing strings are due to a typo or things getting out of sync.

Additionally, the UI text could be updated in the code at any time, and the docs very easily get out of sync.

Add shortcodes to mark UI text (gitlab-org/technical-writing/docs-gitlab-com!2601 - merged) introduces two shortcodes, {{< ui text=" " >}} for GitLab UI text and {{< external-ui text=" " >}} for UI text belonging to another product.

This MR:

  • Makes use of the new shortcodes in one file to demonstrate both ui and external-ui.
  • Adds a test that verifies every ui string against the gitlab.pot file. It does not check UI text that still uses simple markdown bold.
  • Shows that UI text namespaces (namespace|ui text) work and ensure the exact correct ui text string is checked in the gitlab.pot file.

Changes

  • doc/integration/jenkins.md is the example page. It mixes GitLab UI text with Jenkins UI text, so it validates both shortcodes: 13 GitLab labels use ui, and 37 Jenkins labels use external-ui. For example:

    1. On the Jenkins server, select {{< external-ui text="Manage Jenkins" >}} > {{< external-ui text="Manage Plugins" >}}.

1. In the left sidebar, select {{< ui text="Settings" >}} > {{< ui text="Integrations" >}}.

  • scripts/lint/check_ui_text.rb is a new checker. It scans Markdown for the ui shortcode and confirms every marked string exists as a msgid in locale/gitlab.pot. It runs over all 2,939 files in doc/ in about half a second, ignoring external-ui shortcodes by design.

    • .gitlab/ci/docs.gitlab-ci.yml adds a docs-lint ui-text job to run the check in CI/CD pipelines, making sure everything stays in sync.

  • lib/gitlab/help/hugo_transformer.rb ensures both shortcodes render as bold in /help. Covered by new examples in the related spec.

  • .vale.ini adds both shortcodes to TokenIgnores so the markup isn't linted by vale.

Demo page findings

One label is deliberately left as plain bold, and one had drifted:

  • **Jenkins**, the name of the integration in GitLab's integration list. It's GitLab UI text, but app/models/integrations/jenkins.rb line 73 returns the title as a plain hardcoded string with no translation call, so it will never be in the pot file. This stays as simple bold for now.
  • **Secret Token**, the GitLab webhook field, was out of sync: the real label is Webhooks|Secret token (not recommended). Updated, but this also suggests the whole section might need to be revisited, or removed, if it's not a recommended feature anymore.

Findings from building the checker

One normalization rule turned out to be necessary:

  • Some product labels end in an ellipsis in the UI but are documented without one. Docs say Search or go to, but the pot msgid is Search or go to… (U+2026). The checker strips a trailing ellipsis from both sides before comparing.

Sample failure output:

UI text not found in locale/gitlab.pot:

  /tmp/neg.md:2: "This Is Definitely Not A Real Label"
  /tmp/neg.md:3: "search or go to"

The second line is a capitalization mismatch, not a missing string. The style guide requires UI text to match the label's case exactly, so the checker catches that too.

Preview

View of the updated Jenkins integration page:

Edited by Marcel Amirault

Merge request reports