TW team pre-launch QA on localized tech docs

Objective

Get TW team sign off on the previously raised concerns around some program areas as well as providing any feedback on the localized site preview.

  1. Please read through all the sections under "Tech docs localization program areas to review" section on this issue and flag anything that doesn't resonate with you.
  2. [Nice to do -up to each person's capacity] "Review the JA site in using the preview link section" on this issue. Please note that not all the content is merged upstream yet. Link to preview environment here. FYI There are two QA environments:

Links of interest

Tech docs localization program areas to review

1. Translation MR cadence and volume. Ownership and merging

Translation requests don't follow a 1:1 relationship with source MRs. Instead, the argo_translation.yml config file monitors English files, and Argo marks them as "updated" when changes are merged. The localization team uses the Argo Asset Dashboard to filter "updated" and "new" files, then select which ones to include in each translation request. This gives us full control over translation MR timing, scope, and volume.

Post-launch, we'll run monthly translation requests to keep pace with English content updates and new files, maintaining a minimum 80% translation coverage target.

The localization team manages the creation and review of all translation MRs on the fork and upstream. Merging these MRs requires acquiring merging rights on https://gitlab.com/gitlab-org. While we would value the TW team's collaboration on merging, we're mindful of the team's capacity limitations. To support a sustainable workflow for all teams involved, we're pursuing merging rights for the localization team and identifying additional teams who can provide merge support as backup.

2. Reviewing and merging AI-assisted translations

To clarify our quality assurance process: AI translations undergo human, but not linguistic, review before reaching production. We've documented our QA process for AI translations, translation workflow diagram, and localized content pipelines in our new Handbook page.

3. Merge conflicts

We consider what’s in the upstream docs projects to be the source of truth. That means we assume the target updates in it are correct or preferred over the translations in the fork.

You can read more about it and see some visuals in this issue: #730 

4. Reverting changes

In reference to https://docs.gitlab.com/user/project/merge_requests/revert_changes/, a translation request will only get created when a source MR is merged. Revert changes applied to open MRs don’t affect the translation workflow because we will only capture the EN update once the MR is merged. A revert change introduced in a merged English MR will be treated as a “content update” and will follow the regular translation process.

5. Docs site versioning, backporting and translation cut-off for GitLab release

Based on #88 (comment 2876130330) and the resulting issue Disable Japanese translations for archived docs... (#744), Japanese will initially be available only for the latest/unreleased docs version. We'll decide post-launch whether to enable Japanese for archived versions.

Long-term, the localization process might need to support backporting workflows. The necessity and timeline will be determined in future iterations, along with potential changes to CI/CD pipeline configuration, merge request handling, and branching. 

Related backlog issue for planning translation request cut-off that will need to align with branching logic: https://gitlab.com/gitlab-com/localization/docs-site-localization/-/issues/700

6. Target updates / community contributions / How to deal with translated files in your MRs documentation update as a developer

In order to track target updates we’ve created two labels that we will monitor to account for target updates in the translation workflow. We now have a “Contributing to translated documentation” section in our new Handbook page that. 

Besides that there are the following mentions in the following docs pages:

This Danger bot message (see previewed example) would let people know not to edit translated unless they are a localization team member. This should help prevent any confusion about the translation contribution process.

7. Pipeline checks on translated docs / Ownership of maintaining/fixing pipelines and linting tools for translation MRs

 Please read through this dedicated pipeline section on our new Handbook page.

8. Handling deprecations, removals and redirects

The below summary is extracted from this issue where all related work happened.

  • Automated cleanup: The lint-i18n-docs job now checks for orphaned files in /doc-locale, flagging any without English equivalents for team review (MR: gitlab-org/technical-writing/docs-gitlab-com!594 (merged))
  • Smart handling for moves: When files move, readers see English content via fallback until translations catch up in the next push
  • Multilingual redirects: Redirect files will be translated and deployed to all language directories, ensuring seamless navigation across all localized sites
  • Redirects script updated to handle all languages MR

Here examples of two redirect scenarios:

Scenario 1: When doc-locale redirect exists

Scenario 2: When doc-locale redirect doesn't exist

Source: https://gitlab.com/gitlab-com/localization/tech-docs-forked-projects/prod/gitlab/-/blob/main-translation/doc-locale/ja-jp/raketasks/cleanup.md?ref_type=heads

9. SEO optimization of the site

Core SEO elements implemented:

Note: there are known issues around hreflang and canonical tags are not yet implemented correctly. However, we're considering this a non-launch blocker as SEO on the EN site can also get optimized together with JA in future iterations.

10. Automatically built pages

Epic reference: &101 (closed) 

Automatically built pages on the English side of docs.gitlab.com will be grabbed and processed through the regular translation workflow as usual. Of course, there will be a lag between the English and the localized versions of these automatically built pages. 

11. Offline /help pages

For this initial localized tech docs site launch, the /help pages will remain unchanged—no modifications to code or functionality. Non-English users accessing /help will see a partially translated interface, but documentation content will display in English. Any clicks on documentation links will redirect users to the English docs at docs.gitlab.com.

Summary and video provided by Lauren here: #80 (comment 2575843520) 

12. Docs maintenance tasks

Decided to be left out of scope for launch. Decision documented here #85 

13. Enabling multilingual search on docs site search bar

We’re not tackling enabling multilingual search on the localized site. A detailed analysis of the scope of work to enable multilingual search via Elasticsearch needs to be carried out. This will be scoped and planned in FY27.

14. “GitLab Pages can only support 1,000 redirects at a time” concern

This is related to the point above and how we’re handling redirects. It shouldn’t be a concern anymore considering this update from GitLab 17.9.

15. Impact on Duo Chat crawler 

A member of the Japan team already opened an issue to get the option to enhance Duo’s instructions to. No traction yet but the team is aware gitlab-org/gitlab#497807 . We have a backlog issue here: #149

Review the JA site in using the preview link

How to provide feedback

  1. Check existing feedback & known issues first
  2. Start a new thread if your feedback is not listed. Include relevant details, screenshots, and steps to reproduce the issue in expandable sections. You can use the bug report template from below.
  3. Provide as much detail as possible, including device/browser information, steps to reproduce, and expected vs. actual outcomes.
## Bug Report Template

#### [Bug Title]
1. **Bug**: [Clear description of what's broken]
2. **Where**: [URL(s) or location where bug occurs]
3. **Reproduce**: [Step-by-step instructions to recreate the issue]
4. **Browser/device**: [Link to https://whatismybrowser.com]
5. **Expected vs Actual**: [What should happen vs what actually happens]
6. **Severity**: [Critical/High/Medium/Low]
7. **Screenshot**: Visual evidence (if applicable)

Known issues

Note

Our translation coverage of the site is not completed yet so it's expected to see many pages untranslated still.

  1. Search in docs site search bar can't be performed in Japanese, only in English.
  2. Content discrepancy between EN and JA. The JA page may not be at 100% sync with all the content that appears in English. There's a disclaimer banner at the top that informs users about this discrepancy and that some translations are AI-assisted.
  3. Homepage links: some links on the JA homepage (docs.gitlab.com/ja-jp) will link out to an English page:
  4. Not localized links pointing to marketing site: all the links in docs.gitlab.com that redirect the user to about.gitlab.com will remain in EN. For example, footer links in the homepage.
  5. 404 error message is only available in English. See reasoning here. We've implemented an fallback mechanism where a non-EN user would see first content in EN than a 404 error message.
  6. The content in the "contribute" menu remains in English in the localized site. Read through rationale here.
    1. The JA page contains a disclaimer that takes you to the main English "Contribute to development" page
    2. A JA user can use the language selector in the top nav to go to the corresponding English "Contribute" page that they're currently seeing.
  7. GitLab Terms of Use are only available in English intentionally and agreed upon with GitLab's Legal Team
  8. GitLab's social media links link out to EN accounts.
  9. Footer links:
    1. "View page source" and Edit in Web IDE redirect to English files.
    2. The "Cookie Settings" link opens up the English GitLab's Privacy Preference Center powered by Onetrust. The translations of that modal are supplied by Onetrust.
Edited by Maria Jose Salmeron Ibáñez