Skip to main content

Multilingual Support for Internal Documentation Site

Overview​

The BT Management internal documentation site supports the following languages:

  • English - Default language
  • Hebrew - Full RTL (Right-to-Left) support

For Users​

Switching Languages​

  1. Click the language selection menu in the top-right corner of the navigation bar
  2. Select your preferred language (English / עברית)
  3. The site will reload with the content and interface in the selected language

What is Translated?​

  • All interface components (buttons, menus, messages)
  • Sidebar titles and labels
  • Header and footer content
  • Navigation messages
  • Homepage and main features

RTL (Right-to-Left)​

When selecting Hebrew:

  • Text displays right-to-left
  • Navigation bar is mirrored
  • Sidebar moves to the right side
  • Entire interface adapts to Hebrew direction

For Developers​

Local Setup​

cd docs/internal
npm install

Running the Site​

In English (default):​

npm start

Site will be available at: http://localhost:3000

In Hebrew:​

npm run start:he

Site will be available at: http://localhost:3000/he/

Building for Production​

# Build all languages
npm run build

# Build Hebrew only
npm run build:he

Creating/Updating Translations​

# Create translation files for Hebrew
npm run write-translations:he

This command will create JSON files in i18n/he/ with all translatable strings.

Folder Structure​

docs/internal/
├── docs/                    # Original English content
├── blog/                    # Original English blog
├── src/                     # Original React components
└── i18n/
    └── he/                  # All Hebrew content
        ├── code.json        # Interface translations (82 strings)
        ├── docusaurus-theme-classic/
        │   ├── footer.json
        │   └── navbar.json
        ├── docusaurus-plugin-content-docs/
        │   └── current/     # Hebrew documentation content
        ├── docusaurus-plugin-content-blog/
        │   └── [Hebrew blog]
        └── docusaurus-plugin-content-pages/
            ├── index.tsx    # Hebrew homepage
            └── components/

Adding a New Language​

  1. Update docusaurus.config.ts:
i18n: {
  defaultLocale: 'en',
  locales: ['en', 'he', 'NEW_LOCALE'],
  localeConfigs: {
    NEW_LOCALE: {
      label: 'Language Name',
      direction: 'ltr', // or 'rtl'
      htmlLang: 'xx-XX',
    },
  },
},
  1. Create translation files:
npm run write-translations -- --locale NEW_LOCALE

  1. Translate JSON files in i18n/NEW_LOCALE/

  2. Copy and adapt content:

xcopy /E /I docs i18n\NEW_LOCALE\docusaurus-plugin-content-docs\current
xcopy /E /I blog i18n\NEW_LOCALE\docusaurus-plugin-content-blog
xcopy /E /I src\pages i18n\NEW_LOCALE\docusaurus-plugin-content-pages
  1. Add scripts to package.json:
{
  "scripts": {
    "start:NEW_LOCALE": "docusaurus start --locale NEW_LOCALE",
    "build:NEW_LOCALE": "docusaurus build --locale NEW_LOCALE"
  }
}

RTL Support​

For RTL languages, add to src/css/custom.css:

html[lang='NEW_RTL_LOCALE'] {
  direction: rtl;
}

html[lang='NEW_RTL_LOCALE'] .navbar__items {
  flex-direction: row-reverse;
}

/* ... additional RTL styles */

Translating React Components​

React components like HomepageFeatures require manual translation:

  1. Copy: src/components/ → i18n/LOCALE/docusaurus-plugin-content-pages/components/
  2. Translate strings within the components
  3. Keep structure and logic identical

Testing​

# Clear cache
npm run clear

# Run in specific language
npm run start:he

# Verify:
# ✓ All text is translated
# ✓ RTL works properly (Hebrew)
# ✓ Navigation functions
# ✓ All pages load without errors

Main Translation Files​

code.json (82 translations)​

Contains all interface strings:

  • Navigation and buttons
  • Error messages
  • Sidebar and breadcrumbs
  • Theme switcher
  • Blog pagination
  • Site title
  • Main menu items
  • External links

footer.json​

  • Footer links
  • Copyright

current.json​

  • Sidebar category labels
  • Module names

Tips and Best Practices​

  1. Maintain consistency: Use the same terminology throughout translations
  2. Pay attention to RTL: Verify all elements display correctly in RTL languages
  3. Translate in context: Understand the context before translating strings
  4. Watch length: Long translations may break layout
  5. Check links: Ensure internal links work in both languages

Common Issues and Solutions​

Issue: "Page Not Found" in Hebrew​

Solution: Ensure content is copied to i18n/he/docusaurus-plugin-content-docs/current/

Issue: Text not translated​

Solution: Run npm run clear then npm start

Issue: RTL not working​

Solution: Check that direction: 'rtl' is set in docusaurus.config.ts and CSS is adapted

Issue: Components not translated​

Solution: React components require manual translation and copying to i18n/LOCALE/docusaurus-plugin-content-pages/components/

Additional Resources​