Skip to content

MULTI_LANGUAGE_SYSTEM.md

Latest commit

 

History

History
443 lines (348 loc) · 11.3 KB

MULTI_LANGUAGE_SYSTEM.md

File metadata and controls

443 lines (348 loc) · 11.3 KB

Complete Multi-Language System Documentation

This comprehensive guide covers the scalable multi-language system implemented for this Jekyll blog, supporting unlimited languages with centralized configuration and professional UI components.

Table of Contents

  1. Quick Start
  2. System Overview
  3. Configuration
  4. Language Detection
  5. Language Switcher UI Components
  6. Translation Management
  7. Implementation Examples
  8. Migration Guide
  9. SEO & Performance
  10. Troubleshooting

Quick Start

Adding a New Language (e.g., Spanish)

  1. Add to _config.yml:
languages:
  es:
    flag: "🇪🇸"
    name: "Español"
    code: "es"
    locale: "es_ES"
    url: "/es/"
  1. Create homepage (es.md)
  2. Create translated pages with translations array
  3. No code changes needed - system automatically includes new language!

Basic Page Translation

---
title: About
lang: en
translations:
  - lang: pt
    url: "/sobre"
  - lang: fr
    url: "/a-propos"
  - lang: es
    url: "/acerca-de"
---

System Overview

Architecture Components

  1. _config.yml - Centralized language configuration
  2. _includes/language-detection.html - Smart language detection logic
  3. Language Switcher Components - Multiple professional UI variations
  4. CSS Styling - Responsive, accessible design
  5. Translation System - Flexible page-to-page translation mapping

Key Features

  • ✅ Unlimited Languages - Add any number of languages through configuration
  • ✅ Automatic Detection - Smart language detection from page/post frontmatter
  • ✅ Professional UI - Multiple dropdown menu styles available
  • ✅ SEO Optimized - Proper hreflang attributes and language-specific URLs
  • ✅ Mobile Responsive - Optimized for all screen sizes
  • ✅ Backward Compatible - Seamless migration from old two-language system
  • ✅ Zero Dependencies - Pure HTML/CSS implementation

Configuration

Language Configuration (_config.yml)

# Multi-language configuration
languages:
  en:
    flag: "🇺🇸"
    name: "English"
    code: "en"
    locale: "en_US"
    url: "/en/"
  pt:
    flag: "🇧🇷"
    name: "Português" 
    code: "pt"
    locale: "pt_BR"
    url: "/pt/"
  fr:
    flag: "🇫🇷"
    name: "Français"
    code: "fr"
    locale: "fr_FR"
    url: "/fr/"

# Default language
default_language: pt

Configuration Properties

  • flag - Emoji flag displayed in UI
  • name - Full language name shown in dropdown
  • code - Short language identifier (used in frontmatter)
  • locale - Full locale code for SEO (hreflang attribute)
  • url - Homepage URL for this language

Language Detection

Enhanced Detection System (language-detection.html)

The system provides sophisticated language detection that:

  • Detects from frontmatter - Checks page.lang and post.lang
  • Supports multiple formats - Works with en, en_US, pt_BR, etc.
  • Falls back gracefully - Uses default language if none specified
  • Provides rich data - Sets multiple variables for easy use

Available Variables After Detection

{% include language-detection.html %}
<!-- Now available: -->
{{ current_lang }}        <!-- Current language code: "en", "pt", "fr" -->
{{ current_lang_config }} <!-- Full language object with all properties -->
{{ available_languages }} <!-- All configured languages -->

Usage in Components

{% include language-detection.html %}
{% if current_lang == "en" %}
  <h1>Welcome</h1>
{% elsif current_lang == "fr" %}
  <h1>Bienvenue</h1>
{% else %}
  <h1>Bem-vindo</h1>
{% endif %}

Language Switcher UI Components

1. Multi-Language Dropdown (language-switcher-multi.html) ⭐ Recommended

Features:

  • Supports unlimited languages automatically
  • Shows current language with checkmark (✓)
  • Right-aligned dropdown menu
  • SEO-friendly hreflang attributes
  • Smart translation URL detection

Usage:

{% include language-detection.html %}
{% include language-switcher-multi.html %}

Appearance:

  • Button: "🇺🇸 EN ▼"
  • Menu: "🇺🇸 English ✓", "🇧🇷 Português", "🇫🇷 Français"

2. Standard Dropdown (language-switcher.html)

Features:

  • Two-language design with checkmark icons
  • Bootstrap glyphicon integration
  • Divider between current and alternative language

3. Compact Dropdown (language-switcher-compact.html)

Features:

  • Minimal flag-only toggle button
  • Space-efficient design
  • Good for tight navigation spaces

CSS Classes and Styling

/* Multi-Language Switcher Styling */
.language-switcher-multi {
  .dropdown-toggle {
    padding: 15px 12px;
    font-weight: 500;
    min-width: 60px;
  }
  
  .dropdown-menu {
    min-width: 140px;
    border-radius: 4px;
    box-shadow: 0 4px 12px rgba(0,0,0,.15);
  }
  
  .current-language {
    color: #1bacaf;
    font-weight: 600;
    background-color: #f8f9fa;
  }
}

Translation Management

Translation Array Format

Use the translations array in frontmatter for multi-language pages:

---
title: About
lang: en
translations:
  - lang: pt
    url: "/sobre"
  - lang: fr
    url: "/a-propos"
  - lang: es
    url: "/acerca-de"
---

Translation URL Priority

The system intelligently finds translation URLs:

  1. Specific translation in translations array
  2. Language homepage as fallback

Language-Specific Navigation

The header automatically adapts navigation based on current language:

{% if current_lang == "en" %}
  {% assign options = "About,Books,Talks,CV,GitStudyCards" | split: ',' %}
{% elsif current_lang == "fr" %}
  {% assign options = "À propos,Livres,Conférences,CV,GitFichas" | split: ',' %}
{% else %}
  {% assign options = "Sobre,Livros,Palestras,CV,GitFichas" | split: ',' %}
{% endif %}

Implementation Examples

Basic Page Implementation

---
layout: page
title: My Page
lang: en
translations:
  - lang: pt
    url: "/minha-pagina"
  - lang: fr
    url: "/ma-page"
---

{% include language-detection.html %}

<h1>
  {% if current_lang == "en" %}
    Welcome to my page
  {% elsif current_lang == "fr" %}
    Bienvenue sur ma page
  {% else %}
    Bem-vindo à minha página
  {% endif %}
</h1>

<!-- Language switcher in sidebar -->
{% include language-switcher-multi.html %}

Blog Post with Multiple Languages

---
layout: post
title: "My Blog Post"
lang: en
translations:
  - lang: pt
    url: "/meu-post"
  - lang: fr
    url: "/mon-article"
tags:
  - english
  - technology
---

Component with Language Support

{% include language-detection.html %}

<div class="welcome-message">
  {% case current_lang %}
    {% when "en" %}
      <h2>Recent Articles</h2>
      <p>Check out the latest posts</p>
    {% when "fr" %}
      <h2>Articles récents</h2>
      <p>Découvrez les derniers articles</p>
    {% else %}
      <h2>Artigos recentes</h2>
      <p>Confira os posts mais recentes</p>
  {% endcase %}
</div>

Migration Guide

From Two-Language System

  1. Update _config.yml - Add language configuration
  2. Replace old detection logic - Use {% include language-detection.html %}
  3. Update page frontmatter - Add translations arrays
  4. Replace language switcher - Use new multi-language component
  5. Test thoroughly - Verify all language switching works

Migration Checklist

  • Add language configuration to _config.yml
  • Update main language pages (en.md, pt.md, add new languages)
  • Replace old translated fields with translations arrays
  • Update all {% if post.lang == "en" %} conditionals
  • Replace language switcher components
  • Test language switching on all pages
  • Verify SEO attributes are correct
  • Check mobile responsiveness

Breaking Changes

  • Language detection variables - Use current_lang instead of manual checks
  • Translation frontmatter - translations array replaces translated field
  • Component includes - New language detection include required

SEO & Performance

SEO Features

  1. Proper hreflang attributes on all language links
  2. Language-specific URLs (/en/, /pt/, /fr/)
  3. Correct locale codes in configuration
  4. Canonical URL structure for each language

Performance Optimizations

  • Minimal overhead - Only loads necessary language data
  • Efficient caching - Language configuration cached by Jekyll
  • No JavaScript - Pure HTML/CSS implementation
  • Fast rendering - Optimized Liquid template logic

Example SEO Output

<a href="/about" hreflang="en_US">🇺🇸 English</a>
<a href="/a-propos" hreflang="fr_FR">🇫🇷 Français</a>
<a href="/sobre" hreflang="pt_BR">🇧🇷 Português</a>

Troubleshooting

Common Issues

Language not detected properly?

  • Check lang field in page frontmatter
  • Verify language is configured in _config.yml
  • Ensure language-detection.html is included
  • Restart Jekyll server after config changes

Dropdown not showing all languages?

  • Verify _config.yml syntax is correct
  • Check Jekyll build logs for errors
  • Ensure all language configurations are complete

Translations not working?

  • Check translations array syntax in frontmatter
  • Verify target pages exist
  • Test fallback to language homepage

Styling issues?

  • Check CSS load order
  • Verify Bootstrap integration
  • Inspect browser dev tools for conflicts

Debug Mode

Add this to any page to debug language detection:

{% include language-detection.html %}
<div class="debug-info" style="background: #f0f0f0; padding: 10px; margin: 10px;">
  <h4>Language Debug Info:</h4>
  <p><strong>Current Language:</strong> {{ current_lang }}</p>
  <p><strong>Available Languages:</strong> {{ available_languages | size }}</p>
  <p><strong>Current Config:</strong> {{ current_lang_config }}</p>
  <p><strong>Page Lang:</strong> {{ page.lang }}</p>
  <p><strong>Post Lang:</strong> {{ post.lang }}</p>
</div>

Performance Monitoring

Monitor these metrics:

  • Page load times across languages
  • Language switcher click-through rates
  • SEO indexing of different language pages
  • Mobile usability scores

Future Enhancements

Planned Features

  • Cookie-based language preference persistence
  • Browser language auto-detection
  • Automatic translation suggestions
  • Language-specific search functionality

Easy Extensions

  • RTL language support (Arabic, Hebrew)
  • Regional variants (en-US vs en-GB)
  • Language-specific date/number formatting
  • Custom language-based theming

Summary

This scalable multi-language system provides:

✅ Easy language management through centralized configuration
✅ Professional UI components with multiple style options
✅ Smart detection logic supporting various language formats
✅ SEO optimization with proper attributes and structure
✅ Mobile responsiveness across all devices
✅ Future-proof architecture ready for unlimited languages

The system automatically scales as you add new languages - just update the configuration and create your content pages. No code changes required! 🌍✨