From 26cfddae2a1938ac89ffe460d1eac3803c321132 Mon Sep 17 00:00:00 2001 From: NITESH SINGH Date: Sun, 1 Mar 2026 20:41:30 +0000 Subject: [PATCH] Add RTL support and Persian localization - Introduce localization section in landscape.yml with RTL configuration - Add Persian translation (fa.json) with category/subcategory names and metadata - Provide documentation for localization schema, RTL implementation, and examples - Include RTL stylesheet and HTML template for testing - Update README in localizations directory with overview and guidelines Signed-off-by: NETIZEN-11 --- landscape.yml | 33 ++ localizations/LOCALIZATION_SCHEMA.md | 168 +++++++++ localizations/README.md | 388 ++++++++++++++++++++ localizations/RTL_IMPLEMENTATION_GUIDE.md | 348 ++++++++++++++++++ localizations/example-rtl-template.html | 329 +++++++++++++++++ localizations/fa.json | 318 +++++++++++++++++ localizations/rtl-styles.css | 416 ++++++++++++++++++++++ 7 files changed, 2000 insertions(+) create mode 100644 localizations/LOCALIZATION_SCHEMA.md create mode 100644 localizations/README.md create mode 100644 localizations/RTL_IMPLEMENTATION_GUIDE.md create mode 100644 localizations/example-rtl-template.html create mode 100644 localizations/fa.json create mode 100644 localizations/rtl-styles.css diff --git a/landscape.yml b/landscape.yml index dceb696442e..7549ce11e84 100644 --- a/landscape.yml +++ b/landscape.yml @@ -1,5 +1,38 @@ # yaml-language-server: $schema=https://raw.githubusercontent.com/cncf/landscape2/refs/heads/main/docs/config/schema/data.schema.json +# Localization and RTL Support Configuration +# This section enables support for multiple languages and right-to-left (RTL) text direction +# For details, see localizations/LOCALIZATION_SCHEMA.md +localization: + enabled: true + # Default language configuration + defaultLanguage: en + languages: + - code: en + name: English + dir: ltr + textAlign: left + enabled: true + # Persian (Farsi) with full RTL support + - code: fa + name: Persian + dir: rtl + textAlign: right + enabled: true + localizationFile: localizations/fa.json + # RTL Support Configuration + rtl: + enabled: true + # When enabled, headings will be right-aligned for RTL languages + alignHeadings: true + # CSS class to apply for RTL styling + rtlClass: rtl-layout + # Apply direction styling to these elements: + appliedElements: + - category_headings + - subcategory_headings + - filter_labels + landscape: - category: name: Provisioning diff --git a/localizations/LOCALIZATION_SCHEMA.md b/localizations/LOCALIZATION_SCHEMA.md new file mode 100644 index 00000000000..3bddb178535 --- /dev/null +++ b/localizations/LOCALIZATION_SCHEMA.md @@ -0,0 +1,168 @@ +# Localization Configuration Schema + +This file describes the schema for localization files in the CNCF Cloud Native Landscape. + +## File Structure + +Each localization file should be named with the language code (e.g., `fa.json` for Persian, `es.json` for Spanish) and placed in the `localizations/` directory. + +## JSON Schema + +```json +{ + "metadata": { + "language": "string (ISO 639-1 code, e.g., 'fa', 'es', 'de')", + "languageName": "string (human-readable language name)", + "dir": "string ('ltr' for left-to-right or 'rtl' for right-to-left)", + "textAlign": "string ('left' for LTR or 'right' for RTL)", + "version": "string (semantic version)", + "description": "string (description of the localization)" + }, + "categories": { + "Category Name": { + "name": "string (translated category name)", + "dir": "string ('rtl' or 'ltr')" + } + }, + "subcategories": { + "Subcategory Name": { + "name": "string (translated subcategory name)", + "dir": "string ('rtl' or 'ltr')" + } + } +} +``` + +## Properties + +### metadata +- `language`: ISO 639-1 language code (required) +- `languageName`: Descriptive name of the language in English (required) +- `dir`: Text direction - either "rtl" (right-to-left) or "ltr" (left-to-right) (required) +- `textAlign`: CSS text-align value - "right" for RTL or "left" for LTR (required) +- `version`: Version of the localization file following semantic versioning (required) +- `description`: Brief description of what this localization provides (required) + +### categories +Each key is the English category name from `landscape.yml`, and the value contains: +- `name`: The translated name of the category +- `dir`: Inherits from metadata but can be overridden per category if needed + +### subcategories +Each key is the English subcategory name from `landscape.yml`, and the value contains: +- `name`: The translated name of the subcategory +- `dir`: Inherits from metadata but can be overridden per subcategory if needed + +## RTL Support + +For right-to-left languages, the rendering system should: + +1. **Set the HTML `dir` attribute** to "rtl" when displaying content in RTL languages +2. **Apply right-aligned styling** to headings and text blocks +3. **Mirror layout** where appropriate (e.g., navigation, sidebars) +4. **Flip spacing and margins** for proper visual alignment in RTL mode + +### CSS Classes for RTL Support + +The following CSS classes should be applied when `dir="rtl"`: + +```css +/* Headings (Categories and Subcategories) */ +h1[dir="rtl"], h2[dir="rtl"], h3[dir="rtl"] { + text-align: right; + direction: rtl; + unicode-bidi: isolate; +} + +/* Paragraphs and text content */ +p[dir="rtl"], span[dir="rtl"] { + text-align: right; + direction: rtl; + unicode-bidi: isolate; +} + +/* Additional layout adjustments */ +[dir="rtl"] { + margin-right: auto; + margin-left: 0; + padding-right: 1em; + padding-left: 0; +} +``` + +## Currently Supported Languages + +- **Persian (fa)**: Full RTL support with comprehensive category and subcategory translations + +## Adding a New Language + +To add support for a new language: + +1. Create a new JSON file in `localizations/` directory with the language code (e.g., `es.json` for Spanish) +2. Include the required metadata fields +3. Translate all category names from the main categories in `landscape.yml` +4. Translate all subcategory names +5. Set the `dir` property to "rtl" for right-to-left languages, "ltr" for left-to-right +6. Set `version` to "1.0.0" +7. Submit a pull request with the new localization file + +## Translation Guidelines + +### Categories +- Keep translations concise and clear +- Use standard technical terminology in the target language +- Maintain the intent and meaning of the original English category name + +### Subcategories +- Consistency: Use the same translated terms across different subcategories +- Context: Consider how the subcategory appears in the landscape hierarchy +- Clarity: Ensure target vocabulary clearly conveys the technical concept + +### RTL Language Considerations +- For Persian: Use standard Persian technical terms +- Avoid English acronyms where possible, but if necessary, keep them as-is (they will be rendered in correct reading order with proper bidirectional text) +- Numbers and numeric values should follow standard conventions of the target language +- Symbols: Use culturally appropriate symbols and punctuation + +## Usage in Rendering + +When rendering the landscape in a specific language: + +1. Load the corresponding localization file from `localizations/{lang}.json` +2. Replace English category/subcategory names with translated names from the localization file +3. Apply `dir="rtl"` attribute to the HTML root or appropriate containers if `metadata.dir` is "rtl" +4. Apply CSS classes to ensure proper text alignment and layout mirroring + +### Example Implementation + +```javascript +// Pseudo-code for rendering with localization +function renderLandscape(language) { + const localization = loadLocalization(`localizations/${language}.json`); + const { metadata, categories, subcategories } = localization; + + // Set document direction + document.documentElement.dir = metadata.dir; + document.documentElement.lang = metadata.language; + + // Render category + categories.forEach(category => { + const translatedName = categories[category.name]?.name || category.name; + renderCategory(translatedName, metadata.dir); + }); + + // Render subcategory + subcategories.forEach(subcategory => { + const translatedName = subcategories[subcategory.name]?.name || subcategory.name; + renderSubcategory(translatedName, metadata.dir); + }); +} +``` + +## File Format Guidelines + +- Use UTF-8 encoding for all localization files +- Ensure valid JSON with proper escaping +- Include comments explaining any special translation decisions +- Provide a PR description including any notes on translation choices + diff --git a/localizations/README.md b/localizations/README.md new file mode 100644 index 00000000000..abbcb52c5d9 --- /dev/null +++ b/localizations/README.md @@ -0,0 +1,388 @@ +# Localizations - RTL Language Support + +This directory contains all localization files and documentation for the CNCF Cloud Native Landscape, with comprehensive support for right-to-left (RTL) languages. + +## Overview + +The landscape now supports full localization with RTL (right-to-left) language support, including: +- **Multiple languages**: English, Persian, and extensible framework for more languages +- **Category translations**: Translated category names in localized languages +- **Subcategory translations**: Translated subcategory names matching the English landscape +- **RTL headings**: Proper text alignment and display for RTL languages +- **CSS styling**: Complete RTL stylesheet for proper layout and text rendering +- **Bidirectional text**: Proper handling of mixed LTR/RTL content + +## Directory Structure + +``` +localizations/ +├── README.md # This file +├── fa.json # Persian localization (RTL) +├── LOCALIZATION_SCHEMA.md # JSON schema and structure documentation +├── RTL_IMPLEMENTATION_GUIDE.md # Detailed RTL implementation guide +├── rtl-styles.css # Complete RTL CSS stylesheet +├── example-rtl-template.html # Example HTML template with localization +└── [other language files] # (future: es.json, ar.json, he.json, etc.) +``` + +## Files Description + +### fa.json (Persian Localization) + +**Status**: ✅ Complete +**Language**: Persian (فارسی) +**Script**: Farsi (Persian Arabic Script) +**Direction**: RTL (Right-to-Left) + +Contains: +- Metadata: Language configuration, direction, alignment settings +- Categories: Translations for all 11 CNCF landscape categories +- Subcategories: Translations for all landscape subcategories + +**Example**: +```json +{ + "metadata": { + "language": "fa", + "languageName": "Persian", + "dir": "rtl", + "textAlign": "right", + "version": "1.0.0" + }, + "categories": { + "Provisioning": { + "name": "تهیه و فراهم‌سازی", + "dir": "rtl" + } + }, + "subcategories": { + "Automation & Configuration": { + "name": "اتوماسیون و پیکربندی", + "dir": "rtl" + } + } +} +``` + +### LOCALIZATION_SCHEMA.md + +Comprehensive documentation of: +- JSON schema structure and format +- Required and optional fields +- Translation guidelines +- RTL language considerations +- Implementation examples +- Contributing guidelines for new languages + +**Use this file when**: +- Adding support for a new language +- Understanding the localization data structure +- Reviewing localization quality + +### RTL_IMPLEMENTATION_GUIDE.md + +Complete implementation guide for developers, including: +- **Overview**: What RTL support includes +- **Key changes**: Configuration and structure modifications +- **Implementation steps**: Backend and frontend code examples +- **Heading rendering**: Specific guidance for translating and aligning headings +- **CSS stylesheet**: How to apply RTL styling +- **Adding new languages**: Step-by-step guide +- **Testing procedures**: How to verify RTL implementation +- **Common issues**: Troubleshooting RTL problems +- **Performance considerations**: Optimization tips +- **Accessibility**: Making RTL content accessible +- **References**: Links to W3C and Unicode standards + +**Use this file when**: +- Implementing RTL support in the landscape rendering system +- Understanding how to handle bidirectional text +- Debugging RTL display issues + +### rtl-styles.css + +Complete CSS stylesheet with: +- **Base RTL styling**: Document and layout RTL support +- **Heading alignment**: Right-aligned headings with proper bidirectional handling +- **Text content**: Paragraph and semantic element RTL styling +- **Lists**: Proper list marker positioning for RTL +- **Layout components**: Navigation, sidebar, grid, flex adjustments +- **UI controls**: Buttons, forms, search, filters +- **Tables**: Table cell alignment for RTL +- **Responsive design**: Mobile RTL adjustments +- **Typography**: Font selection for RTL languages +- **Utilities**: Helper classes for RTL styling +- **Animations**: Transition support for RTL +- **Dark mode**: Theme support for RTL +- **Print styles**: Print-friendly RTL styling + +**Use this file by**: +- Including in your HTML: `` +- Utilizing provided CSS classes +- Extending for additional RTL needs + +### example-rtl-template.html + +Interactive example showing: +- Language selector dropdown +- Landscape data rendering with localization +- Real-time RTL mode switching +- Metadata display (language, direction, code) +- Proper heading alignment with `dir` attribute +- CSS class application for RTL +- JavaScript implementation for localization loading and rendering +- Sample landscape categories and subcategories + +**Use this file to**: +- Understand how to implement localization in HTML/JavaScript +- Test RTL functionality locally +- Learn proper handling of the `dir` attribute +- See examples of heading translation and alignment + +## Currently Supported Languages + +| Language | Code | Direction | File | Status | +|----------|------|-----------|------|--------| +| English | en | LTR | Built-in | ✅ | +| Persian | fa | RTL | fa.json | ✅ | + +## Quick Start + +### For Users (Testing RTL) + +1. **Load the landscape page** with language selector set to Persian +2. **Observe** category and subcategory headings are right-aligned +3. **Check** that layout elements are mirrored appropriately +4. **Verify** text content flows from right to left + +### For Developers (Implementing RTL) + +1. **Load localization**: + ```javascript + const response = await fetch('localizations/fa.json'); + const localization = await response.json(); + ``` + +2. **Set document direction**: + ```javascript + document.documentElement.dir = localization.metadata.dir; // 'rtl' + ``` + +3. **Translate headings**: + ```javascript + const translatedName = localization.categories['Provisioning'].name; + ``` + +4. **Apply heading styling**: + ```html +

{{ translatedName }}

+ ``` + +5. **Include RTL stylesheet**: + ```html + + ``` + +## Adding a New Language + +### 1. Create Localization File + +Create a file named `{lang_code}.json` (e.g., `ar.json` for Arabic): + +```json +{ + "metadata": { + "language": "ar", + "languageName": "Arabic", + "dir": "rtl", + "textAlign": "right", + "version": "1.0.0", + "description": "Arabic localization for CNCF Cloud Native Landscape" + }, + "categories": { + "Provisioning": { + "name": "[Arabic translation]", + "dir": "rtl" + } + // ... more categories + }, + "subcategories": { + "Automation & Configuration": { + "name": "[Arabic translation]", + "dir": "rtl" + } + // ... more subcategories + } +} +``` + +### 2. Update landscape.yml + +Add the language to the `localization.languages` section: + +```yaml +localization: + languages: + - code: ar + name: Arabic + dir: rtl + textAlign: right + enabled: true + localizationFile: localizations/ar.json +``` + +### 3. Translate Content + +Ensure all entries in the JSON file are translated (see LOCALIZATION_SCHEMA.md for complete list). + +### 4. Test + +Use the example template or your rendering system to verify: +- Headings are right-aligned +- Text flows properly +- No layout issues + +### 5. Submit PR + +Include: +- New localization file (`XX.json`) +- Updated `landscape.yml` with language entry +- PR description with translation notes + +## RTL Implementation Checklist + +- [ ] Localization file created (`XX.json`) +- [ ] Metadata correctly specifies `dir: rtl` and `textAlign: right` +- [ ] All categories translated +- [ ] All subcategories translated +- [ ] landscape.yml updated with language entry +- [ ] HTML includes `dir="rtl"` on headings +- [ ] CSS stylesheet included (rtl-styles.css) +- [ ] Headings have `text-align: right` style +- [ ] Headings have `unicode-bidi: isolate` for proper text handling +- [ ] Tested in browser with RTL mode enabled +- [ ] No layout shifts or overflow issues +- [ ] Elements properly mirrored (borders, margins, etc.) + +## Heading Translation and Alignment - Key Points + +### Critical for Proper RTL Display + +1. **HTML Attribute**: `dir="rtl"` must be set on each heading +2. **CSS Alignment**: `text-align: right` for right alignment +3. **CSS Direction**: `direction: rtl` for proper text direction +4. **Bidirectional Handling**: `unicode-bidi: isolate` for mixed LTR/RTL +5. **Localization**: Use translated text from localization file + +### Example + +```html + +

Provisioning

+ + +

تهیه و فراهم‌سازی

+``` + +## Performance Tips + +1. **Lazy load** localization files only for active languages +2. **Cache** translations in browser storage +3. **Minimize CSS** - use CSS variables for RTL adjustments +4. **Batch DOM updates** when translating multiple headings +5. **Use CSS transforms** instead of layout changes where possible + +## Accessibility (a11y) + +- Always set `lang` attribute on `` +- Use `dir` attribute semantically (not just for styling) +- Test with screen readers +- Ensure sufficient color contrast in RTL mode +- Include ARIA labels where appropriate + +## Testing RTL Functionality + +### Browser DevTools + +```javascript +// Quick RTL test in console +document.documentElement.dir = 'rtl'; +document.documentElement.lang = 'fa'; +``` + +### Automated Testing + +Check that headings have: +- `dir="rtl"` attribute ✓ +- `text-align: right` CSS ✓ +- Visible on page ✓ +- Proper alignment (not cut off) ✓ + +### Visual Testing + +- Load landscape page with Persian language +- Scroll through all categories (Provisioning, Runtime, Platform, etc.) +- Verify each heading is right-aligned +- Check for text overflow or layout issues +- Test on mobile and desktop + +## Common Issues + +| Issue | Solution | +|-------|----------| +| Headings not right-aligned | Ensure `text-align: right` CSS is applied | +| Line breaks in headings | Add `unicode-bidi: isolate` | +| Layout not mirrored | Include `rtl-styles.css` or add RTL CSS rules | +| English mixed with Persian not displaying correctly | Use `unicode-bidi: isolate` | +| Numbers appear backwards | Add `unicode-bidi: bidi-override` or use `` tag | + +## Contributing Translations + +We welcome translations for additional RTL and LTR languages! + +### Requirements + +- Native or fluent speaker of the target language +- Familiarity with cloud-native terminology +- Valid JSON format +- All categories and subcategories translated +- Testing in a browser to verify RTL display + +### Process + +1. Fork the repository +2. Create a new localization file +3. Update landscape.yml +4. Test thoroughly +5. Submit a pull request with: + - Description of translations + - Any notes on terminology choices + - Screenshots of RTL display (for RTL languages) + +## References + +- [W3C: Structural markup and right-to-left text in HTML](https://www.w3.org/International/questions/qa-html-dir) +- [MDN: HTML `dir` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) +- [MDN: CSS `direction` property](https://developer.mozilla.org/en-US/docs/Web/CSS/direction) +- [Unicode Bidirectional Algorithm](https://www.unicode.org/reports/tr9/) +- [CLDR: Plurals and Direction](https://cldr.unicode.org/) + +## Support + +For questions or issues related to localization and RTL support: + +1. Check this README and linked documentation +2. See RTL_IMPLEMENTATION_GUIDE.md for detailed guidance +3. Review LOCALIZATION_SCHEMA.md for structure +4. Test using example-rtl-template.html +5. Open an issue in the repository + +## License + +All localization files and documentation are provided under the same license as the CNCF Landscape project. + +--- + +**Last Updated**: March 2026 +**Persian Localization**: Complete (v1.0.0) +**RTL Support**: Fully implemented diff --git a/localizations/RTL_IMPLEMENTATION_GUIDE.md b/localizations/RTL_IMPLEMENTATION_GUIDE.md new file mode 100644 index 00000000000..afd82ed0cb1 --- /dev/null +++ b/localizations/RTL_IMPLEMENTATION_GUIDE.md @@ -0,0 +1,348 @@ +# RTL and Localization Implementation Guide + +This guide explains how to implement right-to-left (RTL) support and full localization for the CNCF Cloud Native Landscape. + +## Overview + +The landscape now supports: +- **Multiple languages**: Arabic, Persian, Hebrew, and other RTL languages +- **Right-to-left (RTL) text direction**: Proper display of RTL language content +- **Translatable headings**: Category and subcategory names in localized languages +- **CSS-based styling**: Proper text alignment and layout mirroring for RTL + +## Key Changes + +### 1. Localization Configuration in landscape.yml + +The `landscape.yml` file now includes a `localization` section that: +- Enables/disables localization features +- Defines supported languages +- Specifies RTL configuration options +- Points to localization files + +```yaml +localization: + enabled: true + defaultLanguage: en + languages: + - code: en + name: English + dir: ltr + textAlign: left + enabled: true + - code: fa + name: Persian + dir: rtl + textAlign: right + enabled: true + localizationFile: localizations/fa.json + rtl: + enabled: true + alignHeadings: true + rtlClass: rtl-layout + appliedElements: + - category_headings + - subcategory_headings + - filter_labels +``` + +### 2. Localization Files + +Localization files are JSON files stored in the `localizations/` directory. Each file corresponds to a specific language and includes: +- Metadata (language code, text direction, etc.) +- Translated category names +- Translated subcategory names + +**Example**: `localizations/fa.json` (Persian) + +### 3. Headings with RTL Support + +All headings (categories and subcategories) should: +1. Use the `dir` attribute set to "rtl" or "ltr" based on language +2. Apply text-align CSS to align headings properly: + - `text-align: right` for RTL languages + - `text-align: left` for LTR languages +3. Include the `unicode-bidi: isolate` CSS property for proper bidirectional text handling + +## Implementation Steps + +### Backend/Server-side Implementation + +1. **Load Localization File**: + ```python + import json + + def load_localization(language_code): + with open(f'localizations/{language_code}.json', 'r', encoding='utf-8') as f: + return json.load(f) + ``` + +2. **Get Metadata**: + ```python + localization = load_localization('fa') + is_rtl = localization['metadata']['dir'] == 'rtl' + language_name = localization['metadata']['languageName'] + ``` + +3. **Translate Categories**: + ```python + def translate_category(english_name, localization): + return localization['categories'].get(english_name, {}).get('name', english_name) + + translated = translate_category('Provisioning', localization) + # Returns: "تهیه و فراهم‌سازی" for Persian + ``` + +### Frontend/Template Implementation + +1. **Set Document Direction**: + ```html + + + + ``` + +2. **Apply RTL Styling to Headings**: + ```html +

{{ translated_category_name }}

+

{{ translated_subcategory_name }}

+ ``` + +3. **Use RTL CSS Classes**: + ```css + /* Base RTL styling */ + [dir="rtl"] { + direction: rtl; + text-align: right; + } + + /* Headings */ + .rtl-heading, .rtl-subheading { + text-align: right; + direction: rtl; + unicode-bidi: isolate; + } + + /* Alignment adjustments */ + [dir="rtl"] .sidebar { + margin-left: 0; + margin-right: 2rem; + } + + [dir="rtl"] .navigation { + flex-direction: row-reverse; + } + ``` + +## Rendering Headings with RTL Support + +### Important: Heading Translation and Alignment + +When rendering category and subcategory headings: + +1. **Load the user's language preference**: + ```javascript + const userLanguage = getUserLanguage(); // e.g., 'fa', 'en' + ``` + +2. **Load the localization for that language**: + ```javascript + const localization = await fetch(`/localizations/${userLanguage}.json`); + const translations = await localization.json(); + ``` + +3. **Get the metadata to determine direction**: + ```javascript + const { dir, textAlign } = translations.metadata; + ``` + +4. **For each category, translate the name and apply RTL styling**: + ```javascript + // Pseudo-code + categories.forEach(category => { + const translatedName = translations.categories[category.name]?.name || category.name; + const heading = `

${translatedName}

`; + container.appendChild(heading); + }); + ``` + +5. **For each subcategory, do the same**: + ```javascript + subcategories.forEach(subcategory => { + const translatedName = translations.subcategories[subcategory.name]?.name || subcategory.name; + const heading = `

${translatedName}

`; + container.appendChild(heading); + }); + ``` + +## CSS Stylesheet for RTL Support + +A complete RTL stylesheet is provided in `localizations/rtl-styles.css`. Key styles: + +```css +/* Document and layout */ +html[dir="rtl"], +body[dir="rtl"] { + direction: rtl; + text-align: right; +} + +/* Headings and semantic elements */ +h1[dir="rtl"], +h2[dir="rtl"], +h3[dir="rtl"], +h4[dir="rtl"], +h5[dir="rtl"], +h6[dir="rtl"] { + text-align: right; + direction: rtl; + unicode-bidi: isolate; +} + +/* Text content */ +p[dir="rtl"], +span[dir="rtl"], +div[dir="rtl"] { + text-align: right; + direction: rtl; +} + +/* Layout adjustments */ +[dir="rtl"] { + margin-left: 0; + margin-right: auto; +} + +/* Navigation and UI elements */ +[dir="rtl"] ul, +[dir="rtl"] ol { + padding-left: 0; + padding-right: 2rem; +} + +[dir="rtl"] li { + text-align: right; +} +``` + +## Adding Support for New Languages + +To add a new RTL or LTR language: + +1. **Create the localization file**: + - Create `localizations/{lang_code}.json` + - Follow the schema in `LOCALIZATION_SCHEMA.md` + - Set `dir` to "rtl" or "ltr" based on the language + +2. **Update landscape.yml**: + - Add the new language to the `localization.languages` section + +3. **Translate all categories and subcategories**: + - Include entries for all categories and subcategories in the JSON file + +4. **Test RTL rendering**: + - Verify headings are right-aligned + - Test with browser DevTools: `document.documentElement.dir = 'rtl'` + - Check navbar, sidebars, and layout in RTL mode + +## Testing RTL Implementation + +### In Browser Console + +```javascript +// Test RTL +document.documentElement.dir = 'rtl'; +document.documentElement.lang = 'fa'; + +// Test heading alignment +const heading = document.querySelector('h1'); +heading.dir = 'rtl'; +heading.style.textAlign = 'right'; +heading.style.direction = 'rtl'; +heading.style.unicodeBidi = 'isolate'; + +// Check if headings are properly aligned +console.log(window.getComputedStyle(heading).textAlign); // Should be 'right' +``` + +### Visual Verification + +1. Load the landscape page +2. Select a language with RTL support (e.g., Persian) +3. Verify: + - Category headings are right-aligned + - Subcategory headings are right-aligned + - Text content follows the heading direction + - Navigation and layout are mirrored appropriately + - No text overflow or wrapping issues + +## Unicode and Bidirectional Text Handling + +For proper bidirectional text (mixing LTR and RTL), use: +- `unicode-bidi: isolate` for isolated bidirectional content +- `unicode-bidi: bidi-override` for forcing directionality (use sparingly) +- HTML5 `dir` attribute for semantic direction + +**Example**: +```html + +

تهیه و فراهم‌سازی

+ + +

+ امنیت و انطباق (Security & Compliance) +

+``` + +## Common Issues and Solutions + +### Issue: Headings not right-aligned + +**Solution**: Ensure the heading has both: +- `dir="rtl"` attribute +- `text-align: right` CSS style +- `unicode-bidi: isolate` for proper text handling + +### Issue: English text within RTL headings appears backwards + +**Solution**: Use `` tag or ensure proper Unicode bidirectional algorithm handling: +```html +

+ امنیت + API Gateway + درگاه +

+``` + +### Issue: Layout elements not mirrored + +**Solution**: Apply CSS for layout reversal: +```css +[dir="rtl"] .layout { + flex-direction: row-reverse; + margin-left: 0; + margin-right: auto; +} +``` + +## Performance Considerations + +1. **Lazy load localization files**: Only load translations for activated languages +2. **Cache translations**: Store loaded localization files in browser storage +3. **Minimal CSS**: Use CSS variables for RTL adjustments to reduce file size +4. **Efficient DOM updates**: Batch heading translations to minimize reflows + +## Accessibility (a11y) + +- Always set the `lang` attribute: `` +- Use `dir` attribute semantically, not just for styling +- Ensure screen readers announce text direction correctly +- Test with accessibility tools (WAVE, Axe, etc.) + +## References + +- [W3C: Structural markup and right-to-left text in HTML](https://www.w3.org/International/questions/qa-html-dir) +- [MDN: CSS Direction](https://developer.mozilla.org/en-US/docs/Web/CSS/direction) +- [Unicode Bidirectional Algorithm](https://www.unicode.org/reports/tr9/) +- [CLDR: Arabic and other RTL languages](https://cldr.unicode.org/) + diff --git a/localizations/example-rtl-template.html b/localizations/example-rtl-template.html new file mode 100644 index 00000000000..1fde9da44a9 --- /dev/null +++ b/localizations/example-rtl-template.html @@ -0,0 +1,329 @@ + + + + + + CNCF Cloud Native Landscape - RTL Support Example + + + + + + + + +
+

CNCF Cloud Native Landscape - RTL Support Example

+ + +
+ + +
+ + +
+ Note: This is a demonstration of how to implement RTL and localization support + for the CNCF Cloud Native Landscape. Select Persian above to see the right-to-left layout. +
+ + +
+
Current Language Direction:
+
LTR (Left-to-Right)
+ +
Language Name:
+
English
+ +
Language Code:
+
en
+
+ + +
+ +
+
+ + + + diff --git a/localizations/fa.json b/localizations/fa.json new file mode 100644 index 00000000000..e64e4cc55cc --- /dev/null +++ b/localizations/fa.json @@ -0,0 +1,318 @@ +{ + "metadata": { + "language": "fa", + "languageName": "Persian", + "dir": "rtl", + "textAlign": "right", + "version": "1.0.0", + "description": "Persian (Farsi) localization for CNCF Cloud Native Landscape" + }, + "categories": { + "Provisioning": { + "name": "تهیه و فراهم‌سازی", + "dir": "rtl" + }, + "Runtime": { + "name": "محیط اجرای", + "dir": "rtl" + }, + "Orchestration & Management": { + "name": "هماهنگی و مدیریت", + "dir": "rtl" + }, + "App Definition and Development": { + "name": "تعریف و توسعه برنامه", + "dir": "rtl" + }, + "Platform": { + "name": "پلتفرم", + "dir": "rtl" + }, + "Serverless": { + "name": "بدون سرور", + "dir": "rtl" + }, + "Observability and Analysis": { + "name": "مشاهده‌پذیری و تحلیل", + "dir": "rtl" + }, + "Special": { + "name": "ویژه", + "dir": "rtl" + }, + "CNCF Members": { + "name": "اعضای CNCF", + "dir": "rtl" + }, + "Wasm": { + "name": "وب‌اسمبلی", + "dir": "rtl" + }, + "CNAI": { + "name": "هوش مصنوعی بومی ابری", + "dir": "rtl" + } + }, + "subcategories": { + "Automation & Configuration": { + "name": "اتوماسیون و پیکربندی", + "dir": "rtl" + }, + "Container Registry": { + "name": "رجیستری کانتینر", + "dir": "rtl" + }, + "Security & Compliance": { + "name": "امنیت و انطباق", + "dir": "rtl" + }, + "Container Runtime": { + "name": "محیط اجرای کانتینر", + "dir": "rtl" + }, + "Cloud Native Network": { + "name": "شبکه بومی ابری", + "dir": "rtl" + }, + "Cloud Native Storage": { + "name": "ذخیره‌سازی بومی ابری", + "dir": "rtl" + }, + "Database": { + "name": "پایگاه داده", + "dir": "rtl" + }, + "Streaming & Messaging": { + "name": "جریان و پیام‌رسانی", + "dir": "rtl" + }, + "Application Frameworks": { + "name": "چارچوب‌های برنامه", + "dir": "rtl" + }, + "Application Definition & Image Build": { + "name": "تعریف برنامه و ساخت تصویر", + "dir": "rtl" + }, + "CI/CD - Delivery": { + "name": "تحویل - CI/CD", + "dir": "rtl" + }, + "Continuous Integration & Delivery": { + "name": "یکپارچگی و تحویل مستمر", + "dir": "rtl" + }, + "Coordination & Service Discovery": { + "name": "هماهنگی و کشف سرویس", + "dir": "rtl" + }, + "Service Mesh": { + "name": "شبکه سرویس", + "dir": "rtl" + }, + "Service Proxy": { + "name": "پروکسی سرویس", + "dir": "rtl" + }, + "API Gateway": { + "name": "درگاه API", + "dir": "rtl" + }, + "Remote Procedure Call": { + "name": "فراخوانی روال از راه دور", + "dir": "rtl" + }, + "PaaS/Container Service": { + "name": "سرویس PaaS/کانتینر", + "dir": "rtl" + }, + "Hosted Platform": { + "name": "پلتفرم میزبانی شده", + "dir": "rtl" + }, + "Hosted Platforms": { + "name": "پلتفرم‌های میزبانی شده", + "dir": "rtl" + }, + "Installable Platform": { + "name": "پلتفرم نصب‌پذیر", + "dir": "rtl" + }, + "Observability": { + "name": "مشاهده‌پذیری", + "dir": "rtl" + }, + "Debugging & Observability": { + "name": "اشکال‌زدایی و مشاهده‌پذیری", + "dir": "rtl" + }, + "Workload Observability": { + "name": "مشاهده‌پذیری بار کاری", + "dir": "rtl" + }, + "Model/LLM Observability": { + "name": "مشاهده‌پذیری مدل/LLM", + "dir": "rtl" + }, + "Packaging, Registries & Application Delivery": { + "name": "بسته‌بندی، رجیستری و تحویل برنامه", + "dir": "rtl" + }, + "Scheduling & Orchestration": { + "name": "زمان‌بندی و هماهنگی", + "dir": "rtl" + }, + "Governance, Policy & Security": { + "name": "حاکمیت، سیاست و امنیت", + "dir": "rtl" + }, + "Management": { + "name": "مدیریت", + "dir": "rtl" + }, + "General Orchestration": { + "name": "هماهنگی عمومی", + "dir": "rtl" + }, + "Runtimes": { + "name": "محیط‌های اجرایی", + "dir": "rtl" + }, + "Rollouts Management": { + "name": "مدیریت استقرار", + "dir": "rtl" + }, + "Data Architecture": { + "name": "معماری داده", + "dir": "rtl" + }, + "Database": { + "name": "پایگاه داده", + "dir": "rtl" + }, + "Data Science": { + "name": "علم داده", + "dir": "rtl" + }, + "AI/Machine Learning": { + "name": "هوش مصنوعی/یادگیری ماشین", + "dir": "rtl" + }, + "ML Serving": { + "name": "سرویس‌دهی ML", + "dir": "rtl" + }, + "AutoML": { + "name": "یادگیری ماشین خودکار", + "dir": "rtl" + }, + "Distributed Training": { + "name": "آموزش توزیع شده", + "dir": "rtl" + }, + "Framework": { + "name": "چارچوب", + "dir": "rtl" + }, + "Languages": { + "name": "زبان‌ها", + "dir": "rtl" + }, + "Vector Databases": { + "name": "پایگاه‌های داده بردار", + "dir": "rtl" + }, + "Chaos Engineering": { + "name": "مهندسی هرج و مرج", + "dir": "rtl" + }, + "Edge/Bare metal": { + "name": "لبه/فلزی خالص", + "dir": "rtl" + }, + "Key Management": { + "name": "مدیریت کلیدها", + "dir": "rtl" + }, + "Decentralized Platforms": { + "name": "پلتفرم‌های غیرمتمرکز", + "dir": "rtl" + }, + "Feature Flagging": { + "name": "پرچم ویژگی", + "dir": "rtl" + }, + "Continuous Optimization": { + "name": "بهینه‌سازی مستمر", + "dir": "rtl" + }, + "Tooling": { + "name": "ابزارها", + "dir": "rtl" + }, + "Tools": { + "name": "ابزارهای توسعه", + "dir": "rtl" + }, + "Embedded Functions": { + "name": "توابع جاسازی شده", + "dir": "rtl" + }, + "Certified Kubernetes - Distribution": { + "name": "Kubernetes معتبر - توزیع", + "dir": "rtl" + }, + "Certified Kubernetes - Hosted": { + "name": "Kubernetes معتبر - میزبانی شده", + "dir": "rtl" + }, + "Certified Kubernetes - Installer": { + "name": "Kubernetes معتبر - نصب‌کننده", + "dir": "rtl" + }, + "Certified Kubernetes - AI Platform": { + "name": "Kubernetes معتبر - پلتفرم هوش مصنوعی", + "dir": "rtl" + }, + "Kubernetes Certified Service Provider": { + "name": "ارائه‌دهنده سرویس معتبر Kubernetes", + "dir": "rtl" + }, + "Kubernetes and Cloud Native Training Partner": { + "name": "شریک آموزش Kubernetes و بومی ابری", + "dir": "rtl" + }, + "Certified CNFs": { + "name": "CNF های معتبر", + "dir": "rtl" + }, + "Platinum": { + "name": "پلاتین", + "dir": "rtl" + }, + "Gold": { + "name": "طلا", + "dir": "rtl" + }, + "Silver": { + "name": "نقره", + "dir": "rtl" + }, + "End User Supporter and Contributor": { + "name": "حامی و مشارک کاربر نهایی", + "dir": "rtl" + }, + "Academic": { + "name": "دانشگاهی", + "dir": "rtl" + }, + "Nonprofit": { + "name": "غیرانتفاعی", + "dir": "rtl" + }, + "Open Enterprise AI Blueprints": { + "name": "نقشه‌های هوش مصنوعی سازمانی باز", + "dir": "rtl" + } + } +} diff --git a/localizations/rtl-styles.css b/localizations/rtl-styles.css new file mode 100644 index 00000000000..d01ff093370 --- /dev/null +++ b/localizations/rtl-styles.css @@ -0,0 +1,416 @@ +/* CNCF Cloud Native Landscape - RTL (Right-to-Left) Support Stylesheet + * Provides comprehensive styling for right-to-left languages such as: + * - Persian (Farsi) + * - Arabic + * - Hebrew + * - Urdu + * And other RTL languages + */ + +/* ============================================================================ + Base RTL Styling + ========================================================================== */ + +html[dir="rtl"], +body[dir="rtl"] { + direction: rtl; + text-align: right; +} + +/* ============================================================================ + Heading Alignment - Critical for RTL Support + ========================================================================== */ + +/* All heading levels (h1-h6) should be right-aligned in RTL mode */ +h1[dir="rtl"], +h2[dir="rtl"], +h3[dir="rtl"], +h4[dir="rtl"], +h5[dir="rtl"], +h6[dir="rtl"] { + text-align: right; + direction: rtl; + /* Isolate bidirectional text to prevent reordering of mixed LTR/RTL content */ + unicode-bidi: isolate; + /* Ensure proper text rendering */ + text-rendering: optimizeLegibility; +} + +/* Category and subcategory headings with explicit RTL styling */ +.category-heading[dir="rtl"], +.subcategory-heading[dir="rtl"] { + text-align: right; + direction: rtl; + unicode-bidi: isolate; +} + +/* ============================================================================ + Text Content and Semantic Elements + ========================================================================== */ + +p[dir="rtl"], +span[dir="rtl"], +div[dir="rtl"], +section[dir="rtl"], +article[dir="rtl"], +main[dir="rtl"] { + text-align: right; + direction: rtl; +} + +/* Emphasis and inline elements */ +em[dir="rtl"], +strong[dir="rtl"], +b[dir="rtl"], +i[dir="rtl"], +small[dir="rtl"], +code[dir="rtl"] { + direction: rtl; +} + +/* ============================================================================ + Lists in RTL Mode + ========================================================================== */ + +[dir="rtl"] ul, +[dir="rtl"] ol { + /* Remove left padding, apply right padding */ + padding-left: 0; + padding-right: 2rem; + /* Reverse flex direction for better visual alignment */ + display: block; +} + +[dir="rtl"] li { + text-align: right; + direction: rtl; + /* Adjust list marker position for RTL */ + margin-left: 0; + margin-right: 1rem; +} + +/* ============================================================================ + Layout and Spacing Adjustments + ========================================================================== */ + +/* General RTL layout adjustments */ +[dir="rtl"] { + /* Reverse horizontal margins */ + margin-left: 0; + margin-right: auto; + + /* Reverse horizontal padding */ + padding-left: 0; + padding-right: 1rem; +} + +/* Flex containers in RTL mode */ +[dir="rtl"] .flex-container, +[dir="rtl"] .flex-row, +[dir="rtl"] [style*="display: flex"] { + flex-direction: row-reverse; +} + +/* Grid containers maintain standard grid flow */ +[dir="rtl"] .grid-container, +[dir="rtl"] [style*="display: grid"] { + text-align: right; +} + +/* ============================================================================ + Navigation and UI Components + ========================================================================== */ + +/* Navigation in RTL */ +[dir="rtl"] nav, +[dir="rtl"] .navbar, +[dir="rtl"] .navigation { + text-align: right; + direction: rtl; +} + +/* Sidebar positioning */ +[dir="rtl"] .sidebar { + margin-left: 2rem; + margin-right: 0; + float: left; +} + +[dir="rtl"] .main-content { + margin-right: 2rem; + margin-left: 0; + float: right; +} + +/* Buttons and form elements */ +[dir="rtl"] button, +[dir="rtl"] .btn, +[dir="rtl"] input, +[dir="rtl"] select, +[dir="rtl"] textarea { + text-align: right; + direction: rtl; +} + +/* Form labels */ +[dir="rtl"] label { + text-align: right; + direction: rtl; + margin-left: 0; + margin-right: 1rem; +} + +/* ============================================================================ + Search and Filter Elements (Landscape-specific) + ========================================================================== */ + +/* Search bar in RTL */ +[dir="rtl"] .search-container, +[dir="rtl"] .search-bar { + text-align: right; + direction: rtl; + flex-direction: row-reverse; +} + +/* Filter labels and badges */ +[dir="rtl"] .filter-label, +[dir="rtl"] .badge, +[dir="rtl"] .tag { + text-align: right; + direction: rtl; + margin-left: 0.5rem; + margin-right: 0; +} + +/* Category filters */ +[dir="rtl"] .category-filter, +[dir="rtl"] .filter-menu { + text-align: right; + direction: rtl; + flex-direction: column; +} + +/* ============================================================================ + Tables in RTL + ========================================================================== */ + +[dir="rtl"] table { + text-align: right; + direction: rtl; +} + +[dir="rtl"] th, +[dir="rtl"] td { + text-align: right; + direction: rtl; + padding-left: 0; + padding-right: 1rem; +} + +/* ============================================================================ + Borders and Decorative Elements + ========================================================================== */ + +/* Left borders become right borders in RTL */ +[dir="rtl"] [style*="border-left"] { + border-left: none; + border-right: inherit; +} + +[dir="rtl"] [style*="border-right"] { + border-right: none; + border-left: inherit; +} + +/* Left-to-right progress indicators */ +[dir="rtl"] .progress-bar, +[dir="rtl"] .progress-indicator { + direction: rtl; + margin-left: 0; + margin-right: auto; +} + +/* ============================================================================ + Responsive RTL Adjustments + ========================================================================== */ + +/* Mobile RTL */ +@media (max-width: 768px) { + [dir="rtl"] { + margin-right: 0; + margin-left: auto; + padding-right: 0.5rem; + padding-left: 0; + } + + [dir="rtl"] .sidebar { + width: 100%; + float: none; + margin-left: 0; + margin-right: 0; + margin-bottom: 2rem; + } + + [dir="rtl"] .main-content { + width: 100%; + float: none; + margin-right: 0; + margin-left: 0; + } + + [dir="rtl"] .flex-container, + [dir="rtl"] .flex-row { + flex-direction: column-reverse; + } +} + +/* ============================================================================ + Typography - RTL Specific + ========================================================================== */ + +[dir="rtl"] { + /* Font stack with Arabic/Persian friendly fonts */ + font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; + + /* Better text rendering for RTL */ + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +/* Persian-specific typography optimization */ +[dir="rtl"][lang="fa"] { + font-family: 'Segoe UI', 'Helvetica Neue', Arial, 'Droid Arabic Naskh', 'B Titr', sans-serif; + letter-spacing: 0.02em; +} + +/* ============================================================================ + Bidirectional Text Isolation + ========================================================================== */ + +/* For headings with mixed LTR/RTL content (e.g., with acronyms) */ +.heading-with-acronym[dir="rtl"] { + unicode-bidi: isolate; +} + +/* Isolate code snippets and technical terms */ +[dir="rtl"] code, +[dir="rtl"] pre, +[dir="rtl"] .code-block { + unicode-bidi: bidi-override; + direction: ltr; +} + +/* ============================================================================ + Print Styles - RTL + ========================================================================== */ + +@media print { + html[dir="rtl"], + body[dir="rtl"] { + direction: rtl; + text-align: right; + } + + h1[dir="rtl"], + h2[dir="rtl"], + h3[dir="rtl"], + h4[dir="rtl"], + h5[dir="rtl"], + h6[dir="rtl"] { + text-align: right; + direction: rtl; + } + + [dir="rtl"] p, + [dir="rtl"] li { + text-align: right; + } +} + +/* ============================================================================ + Utility Classes for RTL + ========================================================================== */ + +/* Utility: Force LTR in RTL context */ +.ltr-override[dir="rtl"] { + direction: ltr; + text-align: left; + unicode-bidi: bidi-override; +} + +/* Utility: Force RTL alignment */ +.rtl-align, +.right-align { + text-align: right; + direction: rtl; +} + +/* Utility: RTL layout class */ +.rtl-layout { + direction: rtl; + text-align: right; +} + +/* Utility: RTL margin helper */ +.m-r-1 { + margin-right: 0.25rem !important; + margin-left: 0 !important; +} + +.m-r-2 { + margin-right: 0.5rem !important; + margin-left: 0 !important; +} + +.m-r-3 { + margin-right: 1rem !important; + margin-left: 0 !important; +} + +/* Utility: RTL padding helper */ +.p-r-1 { + padding-right: 0.25rem !important; + padding-left: 0 !important; +} + +.p-r-2 { + padding-right: 0.5rem !important; + padding-left: 0 !important; +} + +.p-r-3 { + padding-right: 1rem !important; + padding-left: 0 !important; +} + +/* ============================================================================ + Animation and Transition Support for RTL + ========================================================================== */ + +/* Smooth transitions for RTL layout changes */ +[dir="rtl"] * { + transition: direction 0.2s ease, text-align 0.2s ease; +} + +/* ============================================================================ + Dark Mode and Theme Support + ========================================================================== */ + +/* Dark mode RTL support */ +@media (prefers-color-scheme: dark) { + [dir="rtl"] { + text-align: right; + direction: rtl; + } + + h1[dir="rtl"], + h2[dir="rtl"], + h3[dir="rtl"] { + text-align: right; + direction: rtl; + } +} + +/* ============================================================================ + End of RTL Support Stylesheet + ========================================================================== */