Option to switch languages

Author: johnsamuelwrites

_config.yml

@@ -33,104 +33,150 @@ plugins:
 # Navigation
 nav:
   - title: "Getting Started"
+    page_id: getting_started
     url: "/en/docs/getting-started/"
     children:
       - title: "Installation"
+        page_id: getting_started__installation
         url: "/en/docs/getting-started/installation/"
       - title: "Quick Start"
+        page_id: getting_started__quick_start
         url: "/en/docs/getting-started/quick-start/"
       - title: "REPL Guide"
+        page_id: getting_started__repl
         url: "/en/docs/getting-started/repl/"
   - title: "Language Guide"
+    page_id: language_guide
     url: "/en/docs/language-guide/"
     children:
       - title: "Overview"
+        page_id: language_guide
         url: "/en/docs/language-guide/"
       - title: "Syntax Reference"
+        page_id: language_guide__syntax
         url: "/en/docs/language-guide/syntax/"
       - title: "Keywords"
+        page_id: language_guide__keywords
         url: "/en/docs/language-guide/keywords/"
       - title: "Control Flow"
+        page_id: language_guide__control_flow
         url: "/en/docs/language-guide/control-flow/"
       - title: "Functions & Classes"
+        page_id: language_guide__functions_classes
         url: "/en/docs/language-guide/functions-classes/"
       - title: "Async & Generators"
+        page_id: language_guide__async_generators
         url: "/en/docs/language-guide/async-generators/"
       - title: "All 17 Languages"
+        page_id: language_guide__all_languages
         url: "/en/docs/language-guide/all-languages/"
       - title: "Guide Français"
+        page_id: language_guide__french
         url: "/en/docs/language-guide/french/"
   - title: "Reference"
+    page_id: reference
     url: "/en/docs/reference/"
     children:
       - title: "Language Concepts"
+        page_id: reference
         url: "/en/docs/reference/"
       - title: "Built-in Aliases"
+        page_id: reference__builtins
         url: "/en/docs/reference/builtins/"
       - title: "Operators"
+        page_id: reference__operators
         url: "/en/docs/reference/operators/"
       - title: "Numerals"
+        page_id: reference__numerals
         url: "/en/docs/reference/numerals/"
       - title: "Date & Time"
+        page_id: reference__datetime
         url: "/en/docs/reference/datetime/"
       - title: "Compatibility Matrix"
+        page_id: reference__compatibility
         url: "/en/docs/reference/compatibility/"
   - title: "WASM Backend"
+    page_id: wasm
     url: "/en/docs/wasm/"
     children:
       - title: "Overview"
+        page_id: wasm
         url: "/en/docs/wasm/"
       - title: "Installation"
+        page_id: wasm__installation
         url: "/en/docs/wasm/installation/"
       - title: "Architecture"
+        page_id: wasm__architecture
         url: "/en/docs/wasm/architecture/"
       - title: "Performance"
+        page_id: wasm__performance
         url: "/en/docs/wasm/performance/"
       - title: "Development"
+        page_id: wasm__development
         url: "/en/docs/wasm/development/"
       - title: "Troubleshooting"
+        page_id: wasm__troubleshooting
         url: "/en/docs/wasm/troubleshooting/"
       - title: "FAQ"
+        page_id: wasm__faq
         url: "/en/docs/wasm/faq/"
       - title: "Upgrade to v0.4"
+        page_id: wasm__upgrade
         url: "/en/docs/wasm/upgrade/"
   - title: "Python Codegen"
+    page_id: codegen
     url: "/en/docs/codegen/"
     children:
       - title: "Overview"
+        page_id: codegen
         url: "/en/docs/codegen/"
       - title: "API Reference"
+        page_id: codegen__api
         url: "/en/docs/codegen/api/"
   - title: "Design"
+    page_id: design
     url: "/en/docs/design/"
     children:
       - title: "Architecture"
+        page_id: design
         url: "/en/docs/design/"
       - title: "Core Specification"
+        page_id: design__core_spec
         url: "/en/docs/design/core-spec/"
       - title: "Frontend Contracts"
+        page_id: design__frontend_contracts
         url: "/en/docs/design/frontend-contracts/"
       - title: "Surface Normalization"
+        page_id: design__surface_normalization
         url: "/en/docs/design/surface-normalization/"
       - title: "Stdlib Localization"
+        page_id: design__stdlib_localization
         url: "/en/docs/design/stdlib-localization/"
       - title: "Related Work"
+        page_id: design__related_work
         url: "/en/docs/design/related-work/"
   - title: "Extending"
+    page_id: extending
     url: "/en/docs/extending/"
     children:
       - title: "Add a Language"
+        page_id: extending
         url: "/en/docs/extending/"
       - title: "Translation Guidelines"
+        page_id: extending__translation
         url: "/en/docs/extending/translation/"
       - title: "CNL Scope"
+        page_id: extending__cnl_scope
         url: "/en/docs/extending/cnl-scope/"
   - title: "Contributing"
+    page_id: contributing
     url: "/en/docs/contributing/"
     children:
       - title: "Development Guide"
+        page_id: contributing
         url: "/en/docs/contributing/"
       - title: "Multilingual Docs Ops"
+        page_id: contributing__multilingual_docs
         url: "/en/docs/contributing/multilingual-docs/"
 
 # Collections

_data/locales.yml

@@ -0,0 +1,10 @@
+- code: en
+  label: English
+  native_label: English
+  docs_enabled: true
+  docs_home_page_id: getting_started
+- code: fr
+  label: French
+  native_label: Francais
+  docs_enabled: true
+  docs_home_page_id: getting_started

_includes/localized-url.html

@@ -0,0 +1,12 @@
+{% assign resolved_url = include.fallback_url | default: '/' %}
+{% assign target_locale = include.locale | default: page.locale | default: 'en' %}
+{% if include.page_id %}
+  {% assign candidates = site.pages | where: "page_id", include.page_id %}
+  {% for candidate in candidates %}
+    {% if candidate.locale == target_locale %}
+      {% assign resolved_url = candidate.url %}
+      {% break %}
+    {% endif %}
+  {% endfor %}
+{% endif %}
+{{ resolved_url | relative_url }}

_includes/sidebar.html

@@ -1,15 +1,19 @@
 {% assign nav = site.nav %}
+{% assign current_locale = page.locale | default: 'en' %}
 <div class="sidebar-nav">
   {% for section in nav %}
+  {% capture section_url %}{% include localized-url.html page_id=section.page_id fallback_url=section.url locale=current_locale %}{% endcapture %}
+  {% assign section_active_prefix = section.page_id | append: '__' %}
   <div class="sidebar-section">
-    <a href="{{ section.url | relative_url }}" class="sidebar-section-title{% if page.url == section.url or page.url contains section.url %} active{% endif %}">
+    <a href="{{ section_url | strip }}" class="sidebar-section-title{% if page.page_id == section.page_id or page.page_id contains section_active_prefix %} active{% endif %}">
       {{ section.title }}
     </a>
     {% if section.children %}
     <ul class="sidebar-items">
       {% for item in section.children %}
+      {% capture item_url %}{% include localized-url.html page_id=item.page_id fallback_url=item.url locale=current_locale %}{% endcapture %}
       <li class="sidebar-item">
-        <a href="{{ item.url | relative_url }}" class="sidebar-link{% if page.url == item.url %} active{% endif %}">
+        <a href="{{ item_url | strip }}" class="sidebar-link{% if page.page_id == item.page_id %} active{% endif %}">
           {{ item.title }}
         </a>
       </li>

_layouts/default.html

@@ -1,5 +1,6 @@
 <!DOCTYPE html>
-<html lang="en" class="dark-theme">
+{% assign current_locale = page.locale | default: 'en' %}
+<html lang="{{ current_locale }}" class="dark-theme">
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
@@ -44,15 +45,44 @@
       </a>
 
       <div class="nav-links" role="navigation">
-        <a href="{{ '/en/docs/getting-started/' | relative_url }}" class="nav-link{% if page.url contains '/getting-started' %} active{% endif %}">Getting Started</a>
-        <a href="{{ '/en/docs/language-guide/' | relative_url }}" class="nav-link{% if page.url contains '/language-guide' %} active{% endif %}">Language Guide</a>
-        <a href="{{ '/en/docs/reference/' | relative_url }}" class="nav-link{% if page.url contains '/reference' %} active{% endif %}">Reference</a>
-        <a href="{{ '/en/docs/wasm/' | relative_url }}" class="nav-link{% if page.url contains '/wasm' %} active{% endif %}">WASM</a>
-        <a href="{{ '/en/docs/design/' | relative_url }}" class="nav-link{% if page.url contains '/design' %} active{% endif %}">Design</a>
+        {% for section in site.nav limit: 5 %}
+        {% capture section_url %}{% include localized-url.html page_id=section.page_id fallback_url=section.url locale=current_locale %}{% endcapture %}
+        {% assign section_active_prefix = section.page_id | append: '__' %}
+        <a href="{{ section_url | strip }}" class="nav-link{% if page.page_id == section.page_id or page.page_id contains section_active_prefix %} active{% endif %}">{{ section.title }}</a>
+        {% endfor %}
         <a href="https://github.com/johnsamuelwrites/multilingual" class="nav-link nav-link-external" target="_blank" rel="noopener noreferrer">
           <svg class="icon-github" viewBox="0 0 24 24" fill="currentColor" width="18" height="18" aria-hidden="true"><path d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z"/></svg>
           GitHub
         </a>
+        {% assign docs_locales = site.data.locales | where: "docs_enabled", true %}
+        {% if docs_locales.size > 1 %}
+        <div class="language-switcher">
+          <label class="language-switcher-label" for="language-switcher">Language</label>
+          <select id="language-switcher" class="language-switcher-select" aria-label="Switch documentation language">
+            {% for locale in docs_locales %}
+              {% assign option_url = '/' %}
+              {% if page.page_id %}
+                {% assign sibling_pages = site.pages | where: "page_id", page.page_id %}
+                {% for sibling in sibling_pages %}
+                  {% if sibling.locale == locale.code %}
+                    {% assign option_url = sibling.url %}
+                    {% break %}
+                  {% endif %}
+                {% endfor %}
+              {% elsif locale.docs_home_page_id %}
+                {% assign home_pages = site.pages | where: "page_id", locale.docs_home_page_id %}
+                {% for home_page in home_pages %}
+                  {% if home_page.locale == locale.code %}
+                    {% assign option_url = home_page.url %}
+                    {% break %}
+                  {% endif %}
+                {% endfor %}
+              {% endif %}
+            <option value="{{ option_url | relative_url }}"{% if locale.code == current_locale %} selected{% endif %}>{{ locale.native_label }}</option>
+            {% endfor %}
+          </select>
+        </div>
+        {% endif %}
       </div>
 
       <button class="nav-toggle" aria-label="Toggle menu" aria-expanded="false">
@@ -87,28 +117,38 @@
           <div class="footer-col">
             <h4>Documentation</h4>
             <ul>
-              <li><a href="{{ '/en/docs/getting-started/' | relative_url }}">Getting Started</a></li>
-              <li><a href="{{ '/en/docs/language-guide/' | relative_url }}">Language Guide</a></li>
-              <li><a href="{{ '/en/docs/reference/' | relative_url }}">Reference</a></li>
-              <li><a href="{{ '/en/docs/wasm/' | relative_url }}">WASM Backend</a></li>
-              <li><a href="{{ '/en/docs/design/' | relative_url }}">Design &amp; Architecture</a></li>
+              {% capture footer_getting_started_url %}{% include localized-url.html page_id='getting_started' fallback_url='/en/docs/getting-started/' locale=current_locale %}{% endcapture %}
+              {% capture footer_language_guide_url %}{% include localized-url.html page_id='language_guide' fallback_url='/en/docs/language-guide/' locale=current_locale %}{% endcapture %}
+              {% capture footer_reference_url %}{% include localized-url.html page_id='reference' fallback_url='/en/docs/reference/' locale=current_locale %}{% endcapture %}
+              {% capture footer_wasm_url %}{% include localized-url.html page_id='wasm' fallback_url='/en/docs/wasm/' locale=current_locale %}{% endcapture %}
+              {% capture footer_design_url %}{% include localized-url.html page_id='design' fallback_url='/en/docs/design/' locale=current_locale %}{% endcapture %}
+              <li><a href="{{ footer_getting_started_url | strip }}">Getting Started</a></li>
+              <li><a href="{{ footer_language_guide_url | strip }}">Language Guide</a></li>
+              <li><a href="{{ footer_reference_url | strip }}">Reference</a></li>
+              <li><a href="{{ footer_wasm_url | strip }}">WASM Backend</a></li>
+              <li><a href="{{ footer_design_url | strip }}">Design &amp; Architecture</a></li>
             </ul>
           </div>
           <div class="footer-col">
             <h4>Languages</h4>
             <ul>
-              <li><a href="{{ '/en/docs/language-guide/all-languages/' | relative_url }}">All 17 Languages</a></li>
-              <li><a href="{{ '/en/docs/language-guide/keywords/' | relative_url }}">Keywords</a></li>
-              <li><a href="{{ '/en/docs/extending/' | relative_url }}">Add a Language</a></li>
-              <li><a href="{{ '/en/docs/extending/translation/' | relative_url }}">Translation Guide</a></li>
+              {% capture footer_all_languages_url %}{% include localized-url.html page_id='language_guide__all_languages' fallback_url='/en/docs/language-guide/all-languages/' locale=current_locale %}{% endcapture %}
+              {% capture footer_keywords_url %}{% include localized-url.html page_id='language_guide__keywords' fallback_url='/en/docs/language-guide/keywords/' locale=current_locale %}{% endcapture %}
+              {% capture footer_extending_url %}{% include localized-url.html page_id='extending' fallback_url='/en/docs/extending/' locale=current_locale %}{% endcapture %}
+              {% capture footer_translation_url %}{% include localized-url.html page_id='extending__translation' fallback_url='/en/docs/extending/translation/' locale=current_locale %}{% endcapture %}
+              <li><a href="{{ footer_all_languages_url | strip }}">All 17 Languages</a></li>
+              <li><a href="{{ footer_keywords_url | strip }}">Keywords</a></li>
+              <li><a href="{{ footer_extending_url | strip }}">Add a Language</a></li>
+              <li><a href="{{ footer_translation_url | strip }}">Translation Guide</a></li>
             </ul>
           </div>
           <div class="footer-col">
             <h4>Project</h4>
             <ul>
               <li><a href="https://github.com/johnsamuelwrites/multilingual" target="_blank" rel="noopener">GitHub</a></li>
               <li><a href="https://github.com/johnsamuelwrites/multilingual/issues" target="_blank" rel="noopener">Issues</a></li>
-              <li><a href="{{ '/en/docs/design/related-work/' | relative_url }}">Related Work</a></li>
+              {% capture footer_related_work_url %}{% include localized-url.html page_id='design__related_work' fallback_url='/en/docs/design/related-work/' locale=current_locale %}{% endcapture %}
+              <li><a href="{{ footer_related_work_url | strip }}">Related Work</a></li>
             </ul>
           </div>
         </div>

assets/css/main.css

@@ -157,6 +157,51 @@ body {
   margin-left: auto;
 }
 
+.language-switcher {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-left: 0.5rem;
+  padding-left: 0.75rem;
+  border-left: 1px solid var(--border-secondary);
+}
+
+.language-switcher-label {
+  font-size: 0.72rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+
+.language-switcher-select {
+  min-width: 8.5rem;
+  appearance: none;
+  background:
+    linear-gradient(180deg, rgba(17, 24, 39, 0.98), rgba(13, 18, 32, 0.98));
+  border: 1px solid var(--border-secondary);
+  border-radius: 999px;
+  color: var(--text-primary);
+  font-family: var(--font-body);
+  font-size: 0.84rem;
+  font-weight: 500;
+  padding: 0.42rem 2rem 0.42rem 0.85rem;
+  cursor: pointer;
+  transition: border-color var(--transition-fast), box-shadow var(--transition-fast), color var(--transition-fast);
+  background-image:
+    linear-gradient(180deg, rgba(17, 24, 39, 0.98), rgba(13, 18, 32, 0.98)),
+    url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='14' height='14' viewBox='0 0 14 14'%3E%3Cpath fill='%2300d4ff' d='M3.2 4.8L7 8.6l3.8-3.8.9.9L7 10.4 2.3 5.7z'/%3E%3C/svg%3E");
+  background-repeat: no-repeat, no-repeat;
+  background-position: 0 0, calc(100% - 0.7rem) 50%;
+  background-size: auto, 0.9rem;
+}
+
+.language-switcher-select:hover,
+.language-switcher-select:focus {
+  border-color: var(--border-primary);
+  box-shadow: 0 0 0 3px rgba(0, 212, 255, 0.08);
+  outline: none;
+}
+
 .nav-link {
   display: flex;
   align-items: center;
@@ -1159,6 +1204,8 @@ body {
   .nav-links { display: none; }
   .nav-toggle { display: flex; }
   .nav-links.open { display: flex; flex-direction: column; position: absolute; top: 100%; left: 0; right: 0; background: var(--bg-header); border-bottom: 1px solid var(--border-secondary); padding: 1rem; gap: 0.25rem; }
+  .language-switcher { width: 100%; margin: 0.5rem 0 0; padding: 0.75rem 0 0; border-left: none; border-top: 1px solid var(--border-secondary); justify-content: space-between; }
+  .language-switcher-select { width: min(100%, 12rem); }
   .footer-grid { grid-template-columns: 1fr; gap: 2rem; }
   .footer-links { grid-template-columns: 1fr 1fr; }
   .stats-strip { gap: 2rem; }
@@ -1441,4 +1488,3 @@ pre:hover .wat-btn { opacity: 1; }
   .main-content { padding: 0; }
   body { background: white; color: black; }
 }
-

assets/js/main.js

@@ -379,6 +379,17 @@ except Exception as _e:
     });
   }
 
+  /* ---- Docs language switcher ---- */
+  const languageSwitcher = document.getElementById('language-switcher');
+  if (languageSwitcher) {
+    languageSwitcher.addEventListener('change', event => {
+      const nextUrl = event.target.value;
+      if (nextUrl) {
+        window.location.href = nextUrl;
+      }
+    });
+  }
+
   /* ---- TOC generation ---- */
   const toc = document.getElementById('toc');
   const article = document.querySelector('.content-body');