Japan team pre-launch QA on localized tech docs

🇯🇵 Production site preview ◀️

Objective 🎯

Conduct a pre-release QA for the upcoming launch in Japanese of https://docs.gitlab.com/

Identify major gaps, inconsistencies, problem areas in the localized version of the site that would make it difficult for end user to complete common tasks or set up workflows when using the localized docs site

Target audience 👥

In-country teams in Japan

QA Environments 🌸

Overall progress can be viewed on Tech Docs Dashboard

Production site preview - this is what is currently merged into master by the Technical Writing team after Localization Team's vetting and what will be available to the end user at launch

Overview of how the docs site is localized ✨

Handbook page - hub of the entirety of how the docs site is localized. Some of the most relevant (to this issue) topics to look over:

What NOT to Focus On ℹ️

  • Comprehensive translation quality review (only flag those issues impacting usability and/or are embarrassing)
  • Search functionality limitations (known post-launch issue)
  • Image localization (excluded from launch)
  • Any other Known Issues listed below

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 a 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.

How to provide feedback 💬

  1. Navigate to the Production site preview
  2. Check existing feedback (in the comments to this issue) & known issues first
  3. 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 templates from below.
  4. Provide as much detail as possible, including device/browser information, steps to reproduce, and expected vs. actual outcomes.

Bug Report Template 🐛 

Bug: [Clear description of what's broken]
Where: [URL(s) or location where bug occurs]
Reproduce: [Step-by-step instructions to recreate the issue]
Browser/device: [Link to https://whatismybrowser.com]
Expected vs Actual: [What should happen vs what actually happens]
Issue Category: [Usability/ Language clarity/ Formatting etc.]
Severity: [Critical/High/Medium/Low]
Screenshot: Visual evidence (if applicable)
Edited by Iryna Rogova