Implement hreflang Tags for Docs Site Localization

Implement proper hreflang tags across the docs site to support SEO for the Japanese localization launch and prevent duplicate content issues. We need to implement hreflang tags to:

  • Indicate language relationships between English and Japanese pages
  • Prevent duplicate content penalties during the brief periods when English fallback content appears in Japanese directories
  • Ensure proper search engine indexing for both language versions

Requirements

1. Hreflang Implementation for Fully Translated Pages

Both English and Japanese pages should include identical hreflang tags:

<link rel="alternate" hreflang="en" href="https://docs.gitlab.com/page-path/" />
<link rel="alternate" hreflang="ja-jp" href="https://docs.gitlab.com/ja-jp/page-path/" />
<link rel="alternate" hreflang="x-default" href="https://docs.gitlab.com/page-path/" />

2. Hreflang for English Fallback Content

When Japanese pages display English fallback content (translations not yet available):

<link rel="alternate" hreflang="en" href="https://docs.gitlab.com/page-path/" />
<link rel="alternate" hreflang="x-default" href="https://docs.gitlab.com/page-path/" />
<!-- No ja-jp hreflang since no Japanese translation exists -->

3. Canonical URL Logic

  • Fully translated Japanese pages: Self-referencing canonical (https://docs.gitlab.com/ja-jp/page-path/)
  • English fallback content: Canonical points to English source (https://docs.gitlab.com/page-path/)
  • English pages: Self-referencing canonical

Technical Implementation

  • Integrate with existing English fallback mechanism
  • Build upon the canonical URL implementation already in place
  • Ensure hreflang tags are dynamically generated based on translation availability

Acceptance Criteria

  • Hreflang tags are correctly implemented for all page types
  • Tags update dynamically when translations become available
  • Implementation works with the existing canonical URL system
  • No duplicate content issues in search engine indexing
  • Proper x-default designation for English as the primary language

Testing

  • Validate hreflang implementation on review environment
  • Test both scenarios: fully translated pages and English fallback content
  • Verify canonical URLs are correctly set in both cases

Related Issues