playbooks

home / skills / harborgrid-justin / lexiflow-premium / internationalization-at-scale

internationalization-at-scale skill

/frontend/.github-skills/internationalization-at-scale

This skill enables scalable internationalization with code-splitting and ICU support, delivering sub-second locale switches and RTL-aware layouts.

npx playbooks add skill harborgrid-justin/lexiflow-premium --skill internationalization-at-scale

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
819 B
---
name: internationalization-at-scale
description: Implement performant i18n pipelines with code-splitting and ICU message support.
---

# Internationalization (i18n) at Scale

## Summary
Implement performant i18n pipelines with code-splitting and ICU message support.

## Key Capabilities
- Dynamically load locale chunks based on user preference.
- Implement ICU message parsing and interpolation.
- Manage bidirectional layout changes for RTL languages.

## PhD-Level Challenges
- Prevent waterfall loading of translation strings.
- Handle layout shifts during locale switching.
- Automate string extraction and synchronization with translation services.

## Acceptance Criteria
- Show sub-second locale switching mechanism.
- Provide valid ICU message usage examples.
- Demonstrate RTL layout mirror correctness.

Overview

This skill shows how to implement performant internationalization pipelines for large web apps, focusing on code-splitting, ICU message support, and RTL handling. It is designed for teams building high-performance, legal-grade applications that require sub-second locale switching and correct bidirectional layouts. The guidance emphasizes practical patterns, measurable acceptance criteria, and avoidance of common scaling pitfalls.

How this skill works

The skill demonstrates a runtime that dynamically loads locale-specific chunks on demand to avoid shipping all translations up front. It integrates an ICU message parser and runtime interpolation to support pluralization, gender, and complex formatted messages. It also outlines layout mirroring and CSS strategy to switch between LTR and RTL without visual jank.

When to use it

  • Large single-page apps where shipping full translation bundles hurts performance
  • Applications requiring advanced ICU features (plurals, select, nested formatting)
  • Products that must support RTL languages and preserve layout integrity
  • Systems that synchronize local source strings with translation services
  • Legal or compliance platforms where accurate localized messaging is critical

Best practices

  • Code-split translations by locale and feature to prevent waterfall loads
  • Use an ICU-compliant library or compile-time validation for message correctness
  • Preload only likely locales and lazy-load less-frequent ones on first use
  • Apply logical CSS mirroring (dir attribute) and avoid hardcoded directional styles
  • Automate string extraction and maintain a canonical source to reduce drift

Example use cases

  • Switch user locale sub-second by fetching a small locale chunk and swapping message catalog
  • Render complex legal notices using ICU messages with pluralization and gender variants
  • Mirror forms, navigation, and iconography when switching to Arabic or Hebrew
  • Batch-extract UI strings and push them to a translation management system for translators
  • Prevent waterfall by batching locale requests and caching decoded messages

FAQ

How do you avoid layout shifts when switching locale?

Prepare style rules for both directions, swap the dir attribute early, and preload critical fonts and locale-specific resources to prevent reflow.

Can ICU messages be validated at build time?

Yes — validate ICU syntax during CI using a parser to catch errors before deployment and fail builds on invalid messages.

How to prevent translation bundle waterfalls?

Group messages by route/feature, lazy-load those bundles, and use runtime caching with ETag or service-worker strategies.