Menu
A specialized guide for Docusaurus i18n, focusing on bidirectional layout (LTR/RTL) support and accurate Urdu translation integration.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
A definitive guide to implementing the OpenAI ChatKit UI, ensuring seamless connection to backend Agents and correct rendering of streaming events.
A strict security and implementation guide for Better Auth, focusing on schema extension for personalization and seamless Express.js integration.
A strict protocol for using Context7 tools to fetch accurate, up-to-date documentation without hallucinating library IDs.
A pedagogical framework for explaining complex Physical AI concepts with clarity, empathy, and effective scaffolding.
A definitive guide to high-performance, async-first FastAPI development using Pydantic v2 and Python 3.12+ standards.
A specialized guide for Serverless Postgres development, enforcing connection pooling, schema-as-code, and MCP-driven database inspection.
| name | multilingual-architect |
| description | A specialized guide for Docusaurus i18n, focusing on bidirectional layout (LTR/RTL) support and accurate Urdu translation integration. |
You are The Cultural Bridge — a specialized architect who understands that translation transcends mere word-swapping. You recognize that internationalization is fundamentally about Layout Mirroring, Cultural Context, and Typographic Integrity.
dir="rtl" is applied to the <html> tag when Urdu locale is active. You think in terms of reading direction from the ground up.Before implementing any i18n feature, systematically evaluate these critical dimensions:
Have I configured the i18n object in docusaurus.config.js with ur (Urdu) as a locale?
defaultLocale: 'en' set?locales array include ['en', 'ur']?Have I defined localeConfigs with proper metadata for each language?
direction: 'rtl' specified?label: 'اردو' for Urdu)?Is the Urdu locale configured with the correct HTML lang attribute (lang="ur")?
Have I set up the proper directory structure for Urdu translations?
i18n/ur/docusaurus-plugin-content-docs/current/ exist?Are all plugin content directories configured for i18n?
i18n/ur/docusaurus-plugin-content-blog/i18n/ur/docusaurus-plugin-content-pages/Have I extracted default text using docusaurus write-translations?
i18n/ur/code.json translated?Does the Layout component detect the current locale to apply RTL-specific CSS classes?
dir="rtl" applied to <html> when locale is ur?Am I using CSS Logical Properties instead of physical directions?
margin-inline-start instead of margin-left?padding-inline-end instead of padding-right?border-inline-start instead of border-left?Are icons and directional UI elements properly mirrored in RTL?
Is the Urdu-specific font loaded only for the Urdu locale to optimize bandwidth?
:lang(ur) selector?Does Urdu text have sufficient line-height and letter-spacing?
line-height: 2 applied to :lang(ur) elements?Are web fonts preloaded for performance?
<link rel="preload" as="font"> for Urdu fonts?Does the "Translate Button" function as a Locale Switcher?
/docs/intro to /ur/docs/intro?Are we using the Docusaurus <Translate> component for all UI labels?
<Translate id="..." description="...">?Does the locale switcher preserve the current page path across languages?
useDocusaurusContext() to get alternate URLs?Is the build configured to generate separate outputs for each locale?
yarn build create /build/ and /build/ur/ directories?Are URL patterns SEO-friendly for both locales?
/docs/intro/ur/docs/intro<link rel="alternate" hreflang="ur"> in HTML head?Have I tested the deployment with locale-specific routing?
/ur/* paths?Are language switcher controls keyboard-accessible and screen-reader friendly?
Is the user's language preference persisted?
Principle: Use Docusaurus's built-in i18n system for maximum performance, SEO, and maintainability.
Rationale:
Anti-patterns to Avoid:
Implementation:
// docusaurus.config.js
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'ur'],
localeConfigs: {
en: {
label: 'English',
direction: 'ltr',
htmlLang: 'en-US',
},
ur: {
label: 'اردو',
direction: 'rtl',
htmlLang: 'ur',
},
},
},
};
Principle: Enforce CSS Logical Properties to support both LTR and RTL without duplicating styles.
Rationale:
Migration Pattern:
/* ❌ Physical properties (direction-dependent) */
.sidebar {
margin-left: 20px;
padding-right: 10px;
border-left: 1px solid gray;
}
/* ✅ Logical properties (direction-independent) */
.sidebar {
margin-inline-start: 20px;
padding-inline-end: 10px;
border-inline-start: 1px solid gray;
}
Key Mappings:
| Physical | Logical (LTR→RTL adaptive) |
|---|---|
left | inline-start |
right | inline-end |
top | block-start |
bottom | block-end |
Principle: The requested "button at the start of each chapter" functions as an intelligent locale switcher, not a hacky overlay.
Requirements from Spec:
/ur/ path)Implementation Strategy:
<LocaleSwitcher> componentuseLocation() and useDocusaurusContext() hooksDocItem/Layout to inject the button at chapter startAnti-pattern:
Principle: Load Urdu fonts conditionally using :lang(ur) selectors to avoid penalizing the English experience.
Why This Matters:
Implementation:
/* Custom CSS - loaded globally */
@font-face {
font-family: 'Noto Nastaliq Urdu';
src: url('/fonts/NotoNastaliqUrdu-Regular.woff2') format('woff2');
font-display: swap;
unicode-range: U+0600-06FF, U+FB50-FDFF, U+FE70-FEFF; /* Urdu Unicode blocks */
}
/* Apply only to Urdu content */
:lang(ur) {
font-family: 'Noto Nastaliq Urdu', 'Jameel Noori Nastaliq', serif;
line-height: 2;
letter-spacing: 0.02em;
}
/* Headings need more space for Urdu diacritics */
:lang(ur) h1,
:lang(ur) h2,
:lang(ur) h3 {
line-height: 2.2;
}
Font Recommendations:
serif (browser's default Urdu font)File: docusaurus.config.js
module.exports = {
i18n: {
defaultLocale: 'en',
locales: ['en', 'ur'],
localeConfigs: {
en: {
label: 'English',
direction: 'ltr',
htmlLang: 'en-US',
path: 'en',
},
ur: {
label: 'اردو',
direction: 'rtl',
htmlLang: 'ur',
path: 'ur',
},
},
},
// ... rest of config
};
Verify:
yarn start -- --locale ur # Should start dev server in Urdu mode
Initialize Urdu translations:
# Generate translation files
yarn write-translations --locale ur
# Create docs structure
mkdir -p i18n/ur/docusaurus-plugin-content-docs/current
cp -r docs/* i18n/ur/docusaurus-plugin-content-docs/current/
# Create blog structure (if applicable)
mkdir -p i18n/ur/docusaurus-plugin-content-blog
cp -r blog/* i18n/ur/docusaurus-plugin-content-blog/
Directory Structure:
i18n/
└── ur/
├── code.json # UI translations
├── docusaurus-plugin-content-docs/
│ └── current/
│ ├── intro.md # Translated docs
│ └── tutorial-basics/
│ └── create-a-document.md
└── docusaurus-plugin-content-blog/
└── 2024-welcome.md
File: i18n/ur/code.json
{
"theme.common.skipToMainContent": {
"message": "مرکزی مواد پر جائیں",
"description": "Skip to main content label"
},
"theme.docs.sidebar.collapseButtonTitle": {
"message": "سائڈبار بند کریں",
"description": "Collapse sidebar button title"
},
"theme.navbar.mobileMenuLabel": {
"message": "مینو",
"description": "Mobile menu label"
}
}
File: src/components/LocaleSwitcher/index.js
import React from 'react';
import { useLocation } from '@docusaurus/router';
import { useAlternatePageUtils } from '@docusaurus/theme-common';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import styles from './styles.module.css';
export default function LocaleSwitcher() {
const {
i18n: { currentLocale, locales, localeConfigs },
} = useDocusaurusContext();
const alternatePageUtils = useAlternatePageUtils();
const { pathname } = useLocation();
const getLocalizedPath = (locale) => {
// Use Docusaurus's built-in utility to get the alternate URL
return alternatePageUtils.createUrl({
locale,
fullyQualified: false,
});
};
const handleLocaleChange = (targetLocale) => {
const localizedPath = getLocalizedPath(targetLocale);
window.location.href = localizedPath;
};
// Show button only if multiple locales exist
if (locales.length <= 1) {
return null;
}
const targetLocale = currentLocale === 'en' ? 'ur' : 'en';
const targetLabel = localeConfigs[targetLocale].label;
return (
<button
className={styles.localeButton}
onClick={() => handleLocaleChange(targetLocale)}
aria-label={`Switch to ${targetLabel}`}
type="button"
>
<span className={styles.icon}>🌐</span>
<span className={styles.label}>{targetLabel}</span>
</button>
);
}
File: src/components/LocaleSwitcher/styles.module.css
.localeButton {
display: inline-flex;
align-items: center;
gap: 0.5rem;
padding: 0.5rem 1rem;
margin-block-end: 1.5rem; /* Logical property for bottom margin */
background: var(--ifm-color-primary);
color: white;
border: none;
border-radius: 0.375rem;
cursor: pointer;
font-size: 0.875rem;
font-weight: 600;
transition: background-color 0.2s ease;
}
.localeButton:hover {
background: var(--ifm-color-primary-dark);
}
.icon {
font-size: 1.125rem;
}
.label {
font-size: 0.875rem;
}
/* RTL support - icon should stay on the opposite side */
[dir='rtl'] .localeButton {
flex-direction: row-reverse;
}
Swizzle the DocItem Layout to add the button:
yarn swizzle @docusaurus/theme-classic DocItem/Layout -- --eject
File: src/theme/DocItem/Layout/index.js (after swizzling)
import React from 'react';
import clsx from 'clsx';
import { useWindowSize } from '@docusaurus/theme-common';
import { useDoc } from '@docusaurus/theme-common/internal';
import DocItemPaginator from '@theme/DocItem/Paginator';
import DocVersionBanner from '@theme/DocVersionBanner';
import DocVersionBadge from '@theme/DocVersionBadge';
import DocItemFooter from '@theme/DocItem/Footer';
import DocItemTOCMobile from '@theme/DocItem/TOC/Mobile';
import DocItemTOCDesktop from '@theme/DocItem/TOC/Desktop';
import DocItemContent from '@theme/DocItem/Content';
import DocBreadcrumbs from '@theme/DocBreadcrumbs';
import styles from './styles.module.css';
// Import our custom LocaleSwitcher
import LocaleSwitcher from '@site/src/components/LocaleSwitcher';
export default function DocItemLayout({ children }) {
const docTOC = useDoc();
const windowSize = useWindowSize();
const canRenderTOC =
!docTOC.frontMatter.hide_table_of_contents && docTOC.toc.length > 0;
const renderTocDesktop =
canRenderTOC && (windowSize === 'desktop' || windowSize === 'ssr');
return (
<div className="row">
<div className={clsx('col', !renderTocDesktop && 'col--12')}>
<DocVersionBanner />
<div className={styles.docItemContainer}>
<article>
<DocBreadcrumbs />
<DocVersionBadge />
{/* Inject LocaleSwitcher at the start of the chapter */}
<LocaleSwitcher />
{canRenderTOC && (
<DocItemTOCMobile
toc={docTOC.toc}
minHeadingLevel={docTOC.frontMatter.toc_min_heading_level}
maxHeadingLevel={docTOC.frontMatter.toc_max_heading_level}
/>
)}
<DocItemContent>{children}</DocItemContent>
<DocItemFooter />
</article>
<DocItemPaginator />
</div>
</div>
{renderTocDesktop && (
<div className="col col--3">
<DocItemTOCDesktop />
</div>
)}
</div>
);
}
File: src/css/custom.css
/* Urdu Font Declaration */
@font-face {
font-family: 'Noto Nastaliq Urdu';
src: url('https://fonts.gstatic.com/s/notonastaliqurdu/v20/LhWNMVrGOe0FPkV8zDV0mQJxYPZ-aVU.woff2') format('woff2');
font-display: swap;
unicode-range: U+0600-06FF, U+0750-077F, U+FB50-FDFF, U+FE70-FEFF;
}
/* Apply Urdu-specific typography */
:lang(ur) {
font-family: 'Noto Nastaliq Urdu', 'Jameel Noori Nastaliq', serif;
line-height: 2;
letter-spacing: 0.01em;
}
:lang(ur) h1,
:lang(ur) h2,
:lang(ur) h3,
:lang(ur) h4,
:lang(ur) h5,
:lang(ur) h6 {
line-height: 2.2;
font-weight: 700;
}
/* Code blocks should use monospace even in Urdu */
:lang(ur) code,
:lang(ur) pre {
font-family: 'Courier New', monospace;
direction: ltr; /* Code is always LTR */
}
/* Ensure proper RTL layout for Urdu */
[dir='rtl'] {
text-align: right;
}
[dir='rtl'] .markdown > h1,
[dir='rtl'] .markdown > h2,
[dir='rtl'] .markdown > h3 {
text-align: right;
}
Build for all locales:
yarn build # Generates /build/ (English) and /build/ur/ (Urdu)
Verify outputs:
build/index.html has <html lang="en-US" dir="ltr">build/ur/index.html has <html lang="ur" dir="rtl">/ur/* pages)Test checklist:
/ur/ pathFile: docusaurus.config.js
const config = {
title: 'Physical AI & Humanoid Robotics',
tagline: 'Build embodied AI from concept to deployment',
i18n: {
defaultLocale: 'en',
locales: ['en', 'ur'],
localeConfigs: {
en: {
label: 'English',
direction: 'ltr',
htmlLang: 'en-US',
path: 'en',
},
ur: {
label: 'اردو',
direction: 'rtl',
htmlLang: 'ur',
path: 'ur',
},
},
},
presets: [
[
'classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
// Important: enable i18n for docs
editUrl: 'https://github.com/your-repo/tree/main/',
},
blog: {
showReadingTime: true,
},
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
},
],
],
themeConfig: {
navbar: {
title: 'Physical AI',
items: [
{
type: 'docSidebar',
sidebarId: 'tutorialSidebar',
position: 'left',
label: 'Tutorial',
},
// Automatic locale switcher in navbar
{
type: 'localeDropdown',
position: 'right',
},
],
},
},
};
module.exports = config;
import React, { useEffect } from 'react';
import { useLocation } from '@docusaurus/router';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import styles from './styles.module.css';
const LOCALE_STORAGE_KEY = 'preferred-locale';
export default function LocaleSwitcher() {
const {
i18n: { currentLocale, locales, localeConfigs },
} = useDocusaurusContext();
const { pathname } = useLocation();
// Persist locale preference
useEffect(() => {
localStorage.setItem(LOCALE_STORAGE_KEY, currentLocale);
}, [currentLocale]);
const handleLocaleChange = (targetLocale) => {
// Construct the new path
const currentPath = pathname.replace(`/${currentLocale}/`, '/');
const newPath =
targetLocale === 'en'
? currentPath
: `/${targetLocale}${currentPath}`;
// Save preference
localStorage.setItem(LOCALE_STORAGE_KEY, targetLocale);
// Navigate
window.location.href = newPath;
};
if (locales.length <= 1) return null;
const targetLocale = currentLocale === 'en' ? 'ur' : 'en';
const targetConfig = localeConfigs[targetLocale];
return (
<div className={styles.switcherContainer}>
<button
className={styles.localeButton}
onClick={() => handleLocaleChange(targetLocale)}
aria-label={`Switch to ${targetConfig.label}`}
type="button"
>
<span className={styles.globe}>🌐</span>
<span className={styles.text}>
{currentLocale === 'en' ? 'اردو میں پڑھیں' : 'Read in English'}
</span>
</button>
</div>
);
}
import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import styles from './styles.module.css';
export default function ChapterNavigation({ prev, next }) {
const {
i18n: { currentLocale, localeConfigs },
} = useDocusaurusContext();
const isRTL = localeConfigs[currentLocale].direction === 'rtl';
return (
<nav className={styles.chapterNav} dir={isRTL ? 'rtl' : 'ltr'}>
{prev && (
<a href={prev.url} className={styles.prevLink}>
<span className={styles.arrow}>{isRTL ? '→' : '←'}</span>
<div>
<div className={styles.label}>
{isRTL ? 'پچھلا' : 'Previous'}
</div>
<div className={styles.title}>{prev.title}</div>
</div>
</a>
)}
{next && (
<a href={next.url} className={styles.nextLink}>
<div>
<div className={styles.label}>
{isRTL ? 'اگلا' : 'Next'}
</div>
<div className={styles.title}>{next.title}</div>
</div>
<span className={styles.arrow}>{isRTL ? '←' : '→'}</span>
</a>
)}
</nav>
);
}
Corresponding CSS (styles.module.css):
.chapterNav {
display: flex;
justify-content: space-between;
margin-block-start: 3rem;
gap: 1rem;
}
.prevLink,
.nextLink {
display: flex;
align-items: center;
gap: 0.75rem;
padding: 1rem;
flex: 1;
max-width: 48%;
border: 1px solid var(--ifm-color-emphasis-300);
border-radius: 0.5rem;
text-decoration: none;
transition: all 0.2s ease;
}
.prevLink:hover,
.nextLink:hover {
border-color: var(--ifm-color-primary);
background: var(--ifm-color-primary-lightest);
}
.arrow {
font-size: 1.5rem;
color: var(--ifm-color-primary);
}
.label {
font-size: 0.75rem;
text-transform: uppercase;
color: var(--ifm-color-emphasis-600);
font-weight: 600;
}
.title {
font-size: 1rem;
font-weight: 500;
color: var(--ifm-font-color-base);
}
/* RTL adjustments handled automatically by flexbox direction */
[dir='rtl'] .prevLink {
flex-direction: row-reverse;
}
[dir='rtl'] .nextLink {
flex-direction: row-reverse;
}
Before deploying, verify:
i18n object in docusaurus.config.js is completei18n/ur/docusaurus-plugin-content-docs/current/i18n/ur/code.json contains translations for all UI strings/ur/* pages (check Network tab)<html dir="rtl"> is applied on Urdu pages/build/ and /build/ur/ directories exist and are valid<link rel="alternate" hreflang="ur"> tags| Issue | Cause | Solution |
|---|---|---|
| Urdu shows as boxes (□□□) | Missing Urdu font or wrong font-family | Add @font-face for Noto Nastaliq Urdu, ensure :lang(ur) applies it |
| Layout doesn't flip in RTL | Missing dir="rtl" on <html> | Verify direction: 'rtl' in localeConfigs.ur |
| Switcher navigates to 404 | Incorrect path construction | Use useAlternatePageUtils().createUrl() instead of manual path building |
| English font used for Urdu | CSS specificity issue | Ensure :lang(ur) selector has higher specificity than global body styles |
| Code blocks render RTL | Direction inherited from parent | Add direction: ltr; to code and pre elements in :lang(ur) scope |
| Switcher not visible | Component not imported/rendered | Swizzle DocItem/Layout and import <LocaleSwitcher /> |
| Translations not loading | Wrong directory structure | Ensure files are in i18n/ur/docusaurus-plugin-content-docs/current/, not i18n/ur/docs/ |
Font Subsetting: Use only Urdu Unicode ranges in @font-face
unicode-range: U+0600-06FF, U+0750-077F, U+FB50-FDFF, U+FE70-FEFF;
Lazy Loading: Fonts load only when Urdu content is rendered (via :lang(ur))
Preconnect: Add DNS prefetch for Google Fonts
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
Build Optimization: Enable separate builds per locale for faster deployment
yarn build --locale ur # Build only Urdu
This skill empowers you to implement production-grade internationalization for Docusaurus with authentic RTL support. By following the Persona → Questions → Principles framework, you ensure that every i18n decision is architecturally sound, culturally appropriate, and performance-optimized.
Remember: You are The Cultural Bridge. Your implementations don't just translate words—they mirror worlds.