Multilingual Deep Linking with URL Hash

Why Deep Linking Matters in Multilingual Content

Deep linking allows users to link directly to specific sections of a page. In documentation, tutorials, and knowledge bases, this enhances shareability, SEO, and user navigation—especially when working with multilingual content.

For example, a user reading the Spanish version of a guide should be able to link directly to a section like "Instalación" and land on that exact heading, not its English counterpart. This behavior also encourages content reuse and seamless collaboration across language teams.

Challenge: Language-Dependent Anchors

The challenge is keeping section anchors consistent or mirrored across translations. Most Jekyll setups use the heading text (slugified) as the id, which changes by language. So the anchor #setup in English might become #instalacion in Spanish.

We’ll solve this by assigning custom, language-agnostic IDs to each section using data files or consistent keys.

Step 1: Use Language-Agnostic IDs

Instead of generating id attributes from translated text, we define them manually and translate only the visible label. For example:

{% raw %}
{% assign section_id = 'installation' %}
<h2 id="{{ section_id }}">{{ site.data.translations[page.lang].sections[section_id] }}</h2>
{% endraw %}

This way, no matter the language, the anchor stays the same: #installation.

Step 2: Update Translations

In your _data/translations/en.yml:

sections:
  installation: "Installation"
  usage: "Usage Guide"

And in _data/translations/es.yml:

sections:
  installation: "Instalación"
  usage: "Guía de uso"

This keeps visible labels localized while keeping anchor IDs universal.

Step 3: Auto Scroll to Hash on Page Load

To ensure the page scrolls to the correct section on load, you don’t need any extra JavaScript. The browser will handle it if the ID exists. But with fixed headers (e.g., sticky navbar), you might need an offset scroll adjustment:

{% raw %}

{% endraw %}

This adds a small delay to ensure layout has loaded before scrolling. Adjust 80 based on your header height.

Step 4: Add Link Icons for Sharing

You can append a link icon to each heading to copy the anchor:

{% raw %}
<h2 id="installation">
  {{ site.data.translations[page.lang].sections.installation }}
  <a href="#installation" class="anchor-link">#</a>
</h2>
{% endraw %}

Style the link in CSS:

.anchor-link {
  text-decoration: none;
  margin-left: 5px;
  opacity: 0.4;
}
.anchor-link:hover {
  opacity: 1;
}

Step 5: Share Anchored Links Across Languages

Since anchors are now universal, switching languages should preserve the hash when navigating. You can do this by appending the hash manually during language switch:

{% raw %}

{% endraw %}

This ensures that when a user switches from English to Spanish, they land on the same section (e.g., #installation) in the other language.

Use Cases

• Linking to specific sections in support documentation
• Referencing parts of multilingual blog posts
• Cross-linking between tutorials across languages

Edge Case: Nonexistent Anchors

If a section is missing in one translation (e.g., due to incomplete work), the anchor will not scroll correctly. You can highlight this in your QA process or fallback by detecting such hashes and showing a warning:

{% raw %}
if (!document.getElementById(id)) {
  alert('Section not available in this language yet.');
}
{% endraw %}

Enhancing SEO and Accessibility

• Anchored headings improve crawlability and indexability
• They help screen reader users with better navigation
• They support WCAG guidelines via aria landmarks

Conclusion

Implementing deep linking across languages significantly improves usability, consistency, and content sharing potential. By standardizing anchor IDs and syncing them with translated text, your Jekyll site becomes more accessible and globally usable.

In the next guide, we’ll explore how to create dynamic breadcrumb trails that also reflect the multilingual structure and user position within a document.