Skip to main content

Translation Feature Migration Guide

Overview​

This document explains the migration from the custom DOM manipulation translation system to Docusaurus's official i18n system.

Previous Approach​

The previous implementation used:

  • Custom DOMTranslate React components to wrap translatable content
  • DOMTranslateHandler to manage translations via DOM manipulation
  • Real-time translation switching without page reloads
  • A custom translation dictionary in the LanguageContext

Current Approach​

The new implementation uses:

  • Docusaurus's official i18n system
  • Separate static site builds for each language
  • English content in docs/ directory
  • Urdu translations in i18n/ur/ directory
  • Language switching loads the appropriate static version

Migration Process​

  1. Removed all DOMTranslate components from documentation files
  2. Configured docusaurus.config.ts with multiple locales
  3. Created proper directory structure for Urdu translations
  4. Updated navbar to show language selector automatically
  5. Removed all custom translation handling code

Benefits of New Approach​

  • More reliable translation functionality
  • Better SEO for each language version
  • Improved performance with static content
  • Native Docusaurus support for i18n features
  • Smoother user experience with static loading

Adding New Translated Content​

To add new translated content:

  1. Create the English version in the docs/ directory
  2. Create the corresponding Urdu translation in i18n/ur/docusaurus-plugin-content-docs/default/
  3. Ensure both files have matching slugs in their frontmatter
  4. Add both to the appropriate sidebar configuration

Troubleshooting​

If translations are not appearing:

  1. Verify that Urdu translation files exist in the correct directory
  2. Check that filenames match between English and Urdu versions
  3. Ensure both files have proper frontmatter with matching slugs
  4. Rebuild the site after adding new translation files