# Code Style and Conventions Standards for Internationalization
This document outlines the code style and conventions standards for internationalization (i18n) in software development. Adhering to these standards ensures maintainability, readability, performance, and consistency across the codebase, while fostering collaboration and reducing errors. These guidelines are designed to be used alongside AI coding assistants such as GitHub Copilot and Cursor, helping developers write high-quality, internationalized code.
## 1. General Formatting and Style
### 1.1 Code Formatting
**Standard:** Consistent code formatting is key to readability.
* **Do This:** Use an automated code formatter like Prettier or ESLint (with appropriate i18n-focused plugins) to enforce consistent indentation, spacing, and line breaks.
"""json
// .prettierrc.json (Example configuration)
{
"semi": true,
"trailingComma": "es5",
"singleQuote": true,
"printWidth": 120,
"tabWidth": 2,
"useTabs": false
}
"""
* **Don't Do This:** Manually format code or rely on inconsistent editor settings.
**Explanation:** Automated formatting eliminates subjective style debates, ensures a uniform look and feel, and makes code easier to read and understand.
### 1.2 Naming Conventions
**Standard:** Use descriptive and consistent naming conventions for i18n-related variables, functions, and files.
* **Do This:** Use clear, self-documenting names, avoiding abbreviations. Use a consistent pattern, e.g., "i18n_key", "localizeMessage", "getSupportedLocales".
"""javascript
const i18n_welcomeMessage = 'welcome.message'; // Key for welcome message translation
function localizeMessage(key, locale) { // Function to retrieve localized message
// ... implementation ...
}
"""
* **Don't Do This:** Use vague or cryptic names like "x", "msg", or "i18n()". Avoid naming conflicts or using reserved keywords.
**Explanation:** Meaningful names significantly improve code readability and reduce cognitive load.
### 1.3 Comments and Documentation
**Standard:** Provide clear and concise comments to explain complex i18n logic or non-obvious decisions.
* **Do This:** Document all functions, classes, and modules related to i18n with JSDoc-style comments. Explain the purpose, parameters, and return values.
"""javascript
/**
* Retrieves a localized message for a given key and locale.
* @param {string} key - The unique identifier for the message.
* @param {string} locale - The desired locale (e.g., 'en-US', 'fr-CA').
* @returns {string} The localized message, or a fallback if not found.
*/
function localizeMessage(key, locale) {
// ... implementation ...
}
"""
* **Don't Do This:** Write redundant comments that merely repeat what the code already says. Avoid commenting out code; remove it instead.
**Explanation:** Well-written documentation simplifies maintenance, debugging, and onboarding for new developers.
## 2. Internationalization-Specific Code Style
### 2.1 Locale Handling and Management
**Standard:** Employ consistent practices for identifying, storing, and switching locales.
* **Do This:** Use standard locale identifiers (BCP 47) such as "en-US", "fr-CA", or "de-DE". Store locale information in a dedicated variable or context.
"""javascript
// React Example
import React, { createContext, useState, useContext } from 'react';
const LocaleContext = createContext();
export const LocaleProvider = ({ children, defaultLocale = 'en-US' }) => {
const [locale, setLocale] = useState(defaultLocale);
const changeLocale = (newLocale) => {
setLocale(newLocale);
};
const value = { locale, changeLocale };
return (
{children}
);
};
export const useLocale = () => useContext(LocaleContext); //Custom Hook to use
"""
* **Don't Do This:** Hardcode locale strings throughout the application. Assume a default locale without explicit configuration.
**Explanation:** Standard locale identifiers ensure interoperability and prevent errors. Centralized locale management simplifies updates and configuration.
### 2.2 Message Formatting and Placeholders
**Standard:** Utilize parameterized messages with placeholders for dynamic content.
* **Do This:** Employ a message formatting library like "Intl.formatMessage" or dedicated i18n libraries (e.g., "i18next", "Fluent") to handle placeholders and formatting options.
"""javascript
import { IntlProvider, FormattedMessage } from 'react-intl';
// Message definition
const messages = {
greeting: "Hello, {name}!",
};
// Usage
"""
* **Don't Do This:** Concatenate strings directly with dynamic content. Use inconsistent placeholder syntax.
**Explanation:** Message formatting libraries handle localization-specific formatting rules (date, number, currency) and provide a consistent interface for dynamic content.
### 2.3 Date, Time, and Number Formatting
**Standard:** Format dates, times, and numbers according to the current locale's conventions.
* **Do This:** Use the "Intl" API ("Intl.DateTimeFormat", "Intl.NumberFormat") or equivalent methods provided by i18n libraries to format these values.
"""javascript
const number = 1234567.89;
const formattedNumber = new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(number); // "1.234.567,89 €"
const date = new Date();
const formattedDate = new Intl.DateTimeFormat('fr-CA').format(date); // "2024-10-27"
"""
* **Don't Do This:** Use JavaScript's default "toString()" or "valueOf()" methods for formatting these values.
**Explanation:** "Intl" API provides locale-aware formatting, ensuring that the values are displayed correctly according to the user's region.
### 2.4 Pluralization
**Standard:** Handle pluralization rules correctly for different languages.
* **Do This:** Utilize "Intl.PluralRules" or the pluralization features offered by i18n libraries to select the appropriate plural form.
"""javascript
const rule = new Intl.PluralRules('fr-FR'); // Or dynamically determine locale
const pluralForm = rule.select(itemCount);
let messageKey = 'item.count.other'; // default value
if (pluralForm === 'one') {
messageKey = 'item.count.one';
}
// Example integration with "react-intl"
"""
"""json
// Localized JSON (different plural forms in French)
{
"item.count.one": "One item",
"item.count.other": "{count} items"
}
"""
* **Don't Do This:** Manually construct plural forms with if/else statements or string concatenation.
**Explanation:** Different languages have varying pluralization rules (e.g., some have only singular and plural, while others have more complex categories). "Intl.PluralRules" and i18n libraries automatically handle these complexities.
### 2.5 Handling Right-to-Left (RTL) Languages
**Standard:** Provide proper support for RTL languages like Arabic and Hebrew.
* **Do This:** Use CSS logical properties ("margin-inline-start", "padding-inline-end") instead of physical properties ("margin-left", "padding-right"). Set the "dir" attribute on the "" or "" element based on the current locale.
"""html
Text content
"""
* **Don't Do This:** Hardcode direction-specific styles without considering the current locale.
**Explanation:** CSS logical properties adapt automatically to the text direction, ensuring correct layout for both LTR and RTL languages.
### 2.6 Fallback Mechanisms
**Standard:** Implement robust fallback mechanisms to handle missing translations.
* **Do This:** Provide a default locale (e.g., "en-US") as a fallback. Display a meaningful error message or a key identifier if a translation is missing.
"""javascript
function localizeMessage(key, locale = 'en-US') {
const translations = getTranslationsForLocale(locale);
if (translations && translations[key]) {
return translations[key];
}
const defaultTranslations = getTranslationsForLocale('en-US'); // fallback
if (defaultTranslations && defaultTranslations[key]) {
return defaultTranslations[key];
}
console.warn("Missing translation for key "${key}" and locale "${locale}"");
return "[${key}]"; // Show key as fallback
}
"""
* **Don't Do This:** Display empty strings or undefined values when a translation is missing. Silently ignore missing translations.
**Explanation:** Fallbacks prevent unexpected errors and provide a better user experience when translations are not available. Displaying the key identifier helps developers quickly identify missing translations.
## 3. Modern Approaches and Patterns
### 3.1 Component-Based Internationalization
**Standard:** Encapsulate i18n logic within reusable components.
* **Do This:** Create custom components for displaying localized text, dates, and numbers. Pass the locale as a prop or use a context API to provide it to the component.
"""jsx
// LocalizedText Component (React example)
import React from 'react';
import { useIntl } from 'react-intl';
const LocalizedText = ({ id, values }) => {
const intl = useIntl();
return intl.formatMessage({ id }, values);
};
export default LocalizedText;
"""
* **Don't Do This:** Scatter i18n logic throughout the application code.
**Explanation:** Component-based i18n promotes code reuse, maintainability, and testability.
### 3.2 Server-Side Rendering (SSR) Considerations
**Standard:** Configure i18n for both client-side and server-side rendering environments.
* **Do This:** Ensure that the correct locale is available during server-side rendering. Pre-load translations for the initial locale on the server. Pass the locale information to the client for hydration.
"""javascript
// Next.js Example (getServerSideProps)
export async function getServerSideProps({ locale }) {
const messages = await import("../messages/${locale}.json");
return {
props: {
messages: messages.default,
locale,
},
};
}
function MyApp({ Component, pageProps }) {
const { messages, locale } = pageProps;
return (
);
}
export default MyApp;
"""
* **Don't Do This:** Rely solely on client-side locale detection in SSR environments, potentially leading to incorrect initial rendering.
**Explanation:** SSR requires special attention to locale handling to ensure that the initial HTML content is rendered correctly.
### 3.3 Lazy Loading Translations
**Standard:** Load translations on demand to improve performance and reduce initial bundle size.
* **Do This:** Split translation files into smaller chunks and load them only when needed. Use dynamic imports or code splitting techniques to achieve lazy loading.
"""javascript
// Dynamic import example
async function loadTranslations(locale) {
try {
const messages = await import("./translations/${locale}.json");
return messages.default;
} catch (error) {
console.error("Failed to load translations for locale "${locale}"", error);
return {};
}
}
"""
* **Don't Do This:** Load all translations upfront, even if they are not immediately needed.
**Explanation:** Lazy loading reduces the initial load time and improves the overall performance of the application, especially for applications that support many languages
### 3.4 ICU Message Syntax
**Standard:** Use ICU Message Syntax for more complex formatting.
* **Do This:** Use ICU syntax for gender agreement, select ordinal, or complex pluralization rules
"""javascript
import {FormattedMessage} from 'react-intl';
//Message definition
const messages = {
itemCount: "{count, plural,
=0 {No items}
one {One item}
other {# items}
}"
}
//Usage
// Renders "5 items"
"""
* **Don't Do This:** Use a simple string concatenation which will cause maintainability issues
**Explanation:** ICU Message syntax allows for clear and concise string translation with the support of plurals, gender and select ordinal
## 4. Technology-Specific Details
These guidelines provide a set of best-practices that can be adopted across different technologies. Below are examples for specific tech stacks.
### 4.1 React and React-Intl
* **Do This:** Utilize "react-intl" library for i18n in React applications. Use hooks like "useIntl" for easy access to formatting functions.
* **Best Practice:** Use "" component for rendering localized text.
* **Example:** See "Component-Based Internationalization" and "ICU Message Syntax" in the above section.
### 4.2 Angular and ngx-translate
* **Do This:** Use "ngx-translate" library for i18n in Angular applications. Use "TranslateService" to load and retrieve translations. Use pipes like "translate" in templates.
* **Best Practice:** Lazy load translation files using "HttpClient" and "TranslateModule.forRoot".
* **Example:**
"""typescript
// app.module.ts
import { HttpClientModule, HttpClient } from '@angular/common/http';
import { TranslateModule, TranslateLoader } from '@ngx-translate/core';
import { TranslateHttpLoader } from '@ngx-translate/http-loader';
export function HttpLoaderFactory(http: HttpClient) {
return new TranslateHttpLoader(http, './assets/i18n/', '.json');
}
@NgModule({
imports: [
HttpClientModule,
TranslateModule.forRoot({
loader: {
provide: TranslateLoader,
useFactory: HttpLoaderFactory,
deps: [HttpClient],
},
defaultLanguage: 'en',
}),
],
})
export class AppModule {}
// component.ts
import { TranslateService } from '@ngx-translate/core';
constructor(private translate: TranslateService) {
translate.setDefaultLang('en');
translate.use('fr');
}
// component.html
{{ 'HOME.TITLE' | translate }}
"""
### 4.3 Vue and vue-i18n
* **Do This:** Utilize "vue-i18n" library for i18n in Vue applications. Use "i18n" instance to manage translations.
* **Best Practice:** Use the "$t" helper function in templates for rendering localized text.
* **Example:**
"""javascript
// main.js
import Vue from 'vue';
import VueI18n from 'vue-i18n';
Vue.use(VueI18n);
const i18n = new VueI18n({
locale: 'fr',
messages: {
en: { message: { hello: 'hello world' } },
fr: { message: { hello: 'bonjour monde' } },
},
});
new Vue({
i18n,
render: (h) => h(App),
}).$mount('#app');
// component.vue
"""
## 5. Common Anti-Patterns
* **Hardcoding strings:** Instead of using keys. This makes it more difficult to find and translate text.
* **Lack of Parameterization:** Makes it difficult to insert dynamic content in translatable strings.
* **Ignoring Context:** Translating the same word differently depending on context is impossible without specific keys.
* **Over-complicating keys:** Avoid extremely long or complex keys. Keep them simple and descriptive.
* **Inconsistent Locale Handling:** Using different locale formats or inconsistent ways of storing the locale across the application.
* **Neglecting RTL Support:** Assuming all languages are left-to-right and not providing proper support for right-to-left languages.
## 6. Performance Optimization Techniques
* **Caching Translations:** Implement caching mechanisms to store frequently accessed translations to reduce lookup times.
* **Using CDNs for Translation Files:** Deliver translation files via CDNs to improve loading speed and reduce server load.
* **Prefetching Translations:** Prefetch translation files for the user's preferred languages to reduce latency and improve perceived performance.
* **Minifying Translation Files:** Minify translation files to reduce their size, which can improve loading times in the browser.
* **Code Splitting Translation Files:** Split translation files into smaller chunks and load them only when needed can significanlty decrease initial loading size.
By following these code style and conventions standards, development teams can create high-quality, maintainable, and performant internationalized applications. These guidelines are intended to be a starting point and should be adapted based on the specific needs of the project and technology stack being used. Remember to stay updated with the latest advancements in i18n best practices and tools.
danielsogl
Created Mar 6, 2025
This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.
The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.
Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.
# Project Overview project: name: 'Your Project Name' description: 'Brief project description' stack: - technology: 'Framework/Language' version: 'X.Y.Z' - technology: 'Database' version: 'X.Y.Z'
# Code Standards standards: style: - 'Use consistent indentation (2 spaces)' - 'Follow language-specific naming conventions' documentation: - 'Include JSDoc comments for all functions' - 'Maintain up-to-date README files' testing: - 'Write unit tests for all new features' - 'Maintain minimum 80% code coverage'
# Security Guidelines security: authentication: - 'Implement proper token validation' - 'Use environment variables for secrets' dataProtection: - 'Sanitize all user inputs' - 'Implement proper error handling'
Be Specific
Maintain Organization
Regular Updates
# Common Patterns Example patterns: components: - pattern: 'Use functional components by default' - pattern: 'Implement error boundaries for component trees' stateManagement: - pattern: 'Use React Query for server state' - pattern: 'Implement proper loading states'
Commit the Rules
.clinerules in version controlTeam Collaboration
Rules Not Being Applied
Conflicting Rules
Performance Considerations
# Basic .clinerules Example project: name: 'Web Application' type: 'Next.js Frontend' standards: - 'Use TypeScript for all new code' - 'Follow React best practices' - 'Implement proper error handling' testing: unit: - 'Jest for unit tests' - 'React Testing Library for components' e2e: - 'Cypress for end-to-end testing' documentation: required: - 'README.md in each major directory' - 'JSDoc comments for public APIs' - 'Changelog updates for all changes'
# Advanced .clinerules Example project: name: 'Enterprise Application' compliance: - 'GDPR requirements' - 'WCAG 2.1 AA accessibility' architecture: patterns: - 'Clean Architecture principles' - 'Domain-Driven Design concepts' security: requirements: - 'OAuth 2.0 authentication' - 'Rate limiting on all APIs' - 'Input validation with Zod'
# Tooling and Ecosystem Standards for Internationalization This document outlines the coding standards related to tooling and ecosystems for Internationalization (i18n). It provides guidelines for selecting, configuring, and effectively utilizing i18n-related libraries, tools, and extensions to ensure maintainable, performant, and secure internationalized applications. ## 1. Recommended Libraries and Tools ### 1.1 Locale Management **Standard:** Use a robust locale management library to handle locale detection, storage, and retrieval. **Do This:** * Use libraries that conform to the Unicode CLDR (Common Locale Data Repository). * Favor libraries that support locale fallbacks (e.g., "en-US" falling back to "en"). * Implement locale resolvers for different sources (e.g., URL, cookies, browser settings). **Don't Do This:** * Manually parse HTTP "Accept-Language" headers without proper validation and security considerations. * Hardcode locale information directly into application logic. **Why:** Effective locale management is fundamental to delivering the right localized content to the end-user. Improper handling can lead to inaccurate localization or security vulnerabilities. **Code Example (JavaScript with "i18next"):** """javascript // npm install i18next i18next-browser-languagedetector i18next-http-backend import i18next from 'i18next'; import Backend from 'i18next-http-backend'; import LanguageDetector from 'i18next-browser-languagedetector'; i18next .use(Backend) .use(LanguageDetector) .init({ fallbackLng: 'en', debug: true, detection: { order: ['querystring', 'cookie', 'localStorage', 'navigator', 'htmlTag', 'path', 'subdomain'], lookupQuerystring: 'lng', lookupCookie: 'i18next', caches: ['localStorage', 'cookie'] }, backend: { loadPath: '/locales/{{lng}}/{{ns}}.json', }, interpolation: { escapeValue: false // not needed for react as it escapes by default } }); export default i18next; //Later in a React component import { useTranslation } from 'react-i18next'; function MyComponent() { const { t, i18n } = useTranslation(); function handleClick(lang) { i18n.changeLanguage(lang); } return ( <div> <button onClick={() => handleClick('en')}>English</button> <button onClick={() => handleClick('fr')}>French</button> <p>{t('greeting')}</p> </div> ); } export default MyComponent; """ **Anti-Pattern:** Forgetting to configure a fallback locale, resulting in application failure if a requested locale is not available. ### 1.2 Message Formatting **Standard:** Use message formatting libraries to manage localized strings with placeholders, pluralization, and gender/number agreement. **Do This:** * Adopt a well-supported message format like ICU MessageFormat. * Use externalized resource files (e.g., ".json", ".properties") to store localized strings. * Abstract message formatting logic into reusable functions or components. **Don't Do This:** * Concatenate strings directly in the code when building localized messages. * Embed formatting rules (pluralization, gender) directly within the application's code. **Why:** Message formatting provides a structured way to handle localized strings and ensures proper handling of grammatical variationsacross languages. It keeps code cleaner, simplifies translation, and enhances maintainability. **Code Example (JavaScript with "i18next" and "i18next-icu"):** """javascript // npm install i18next i18next-icu import i18next from 'i18next'; import ICU from 'i18next-icu'; i18next.use(ICU).init({ lng: 'en', fallbackLng: 'en', resources: { en: { translation: { 'unreadMessages': 'You have {count, plural, =0 {no unread messages} =1 {one unread message} other {# unread messages}}' } }, fr: { translation: { 'unreadMessages': 'Vous avez {count, plural, =0 {aucun message non lu} =1 {un message non lu} other {# messages non lus}}' } } } }); const count = 3; const message = i18next.t('unreadMessages', { count: count }); console.log(message); // Output: 3 unread messages (if lng is 'en') or 3 messages non lus (if lng is 'fr') """ **Anti-Pattern:** Using simple string replacement without considering pluralization rules, resulting in grammatically incorrect messages in some locales. ### 1.3 Date, Time, and Number Formatting **Standard:** Utilize locale-aware formatting functions from standard libraries or dedicated packages for dates, times, and numbers. **Do This:** * Use "Intl.DateTimeFormat" and "Intl.NumberFormat" in JavaScript for native locale-aware formatting. * Configure the format options (e.g., date style, currency) to match the UX requirements. * Handle time zones correctly based on user preferences. **Don't Do This:** * Manually format dates, times, or numbers using string manipulation or regular expressions. * Assume a single format works for all locales. **Why:** Date, time, and number formats differ significantly across cultures. Using locale-aware formatting ensures information is presented correctly to the user. **Code Example (JavaScript with "Intl"):** """javascript const now = new Date(); const number = 1234567.89; // Date formatting const dateFormatter = new Intl.DateTimeFormat('fr-CA', { dateStyle: 'full', timeStyle: 'short' }); console.log(dateFormatter.format(now)); // Output: vendredi 17 mai 2024 à 10 h 30 HE // Number formatting (Canadian French) const numberFormatter = new Intl.NumberFormat('fr-CA', { style: 'currency', currency: 'CAD' }); console.log(numberFormatter.format(number)); // Output: 1 234 567,89 $ CA //Number Formatter (German) const numberFormatterDE = new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }); console.log(numberFormatterDE.format(number)); // Output: 1.234.567,89 € """ **Anti-Pattern:** Displaying dates in "MM/DD/YYYY" format to users in countries where "DD/MM/YYYY" is the standard. ### 1.4 Translation Management Systems (TMS) **Standard:** Integrate with a TMS to streamline the translation workflow and maintain consistency across localized content. **Do This:** * Choose a TMS that supports the message formats used in your application. * Automate the process of extracting translatable strings from the codebase and importing translated content back. * Use TM features like translation memory and terminology management. **Don't Do This:** * Rely on manual copy-pasting of strings between the codebase and translation tools. * Neglect the importance of terminology management, leading to inconsistent translations. **Why:** TMS integration improves the efficiency, accuracy, and consistency of the translation process, especially in large-scale projects. **Code Example (Illustrative - connecting to a generic TMS API):** """javascript // This is PSEUDO-CODE. Actual implementation depends on your TMS system. async function uploadStringsToTMS(strings) { const tmsApiUrl = 'https://example.com/tms/api/upload'; try { const response = await fetch(tmsApiUrl, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TMS_API_KEY' }, body: JSON.stringify({ strings }) }); if (!response.ok) { throw new Error("TMS API error: ${response.status} ${response.statusText}"); } const data = await response.json(); console.log('Strings uploaded to TMS successfully:', data); } catch (error) { console.error('Failed to upload strings to TMS:', error); } } // Example Usage const translatableStrings = { 'greeting': 'Hello, world!', 'farewell': 'Goodbye!' }; uploadStringsToTMS(translatableStrings); """ **Anti-Pattern:** Lack of integration between developer tools and TMS, resulting in manual extraction and integration of localization files. ### 1.5 Linting and Static Analysis Tools **Standard:** Use linters and static analysis tools to enforce i18n coding standards and detect potential issues early in the development lifecycle. **Do This:** * Configure linters to check for hardcoded strings, missing translations, and incorrect message formatting. * Integrate linting into the CI/CD pipeline to automatically check and enforce coding standards. * Use static analysis tools to find potential vulnerabilities related to locale injection or improper Unicode handling. **Don't Do This:** * Ignore linting warnings or disable i18n-related rules. * Rely solely on manual code reviews to catch i18n issues. **Why:** Automated linting and static analysis improve the quality and consistency of i18n code, reduce the risk of errors, and make the codebase easier to maintain. **Code Example (Configuration with ESLint):** """javascript // .eslintrc.js module.exports = { "plugins": [ "i18next" ], "rules": { "i18next/no-literal-string": ["error", { markupOnly: true }], } }; """ Then, make use of the plugin in your JavaScript/JSX file. """javascript // Example.jsx import React from 'react'; import { useTranslation } from 'react-i18next'; function Example() { const { t } = useTranslation(); return ( <div> <h1>{t('welcome')}</h1> // Correct usage <p>Hello World</p> // ESLint will flag this as an error – hardcoded string </div> ); } export default Example; """ **Anti-Pattern:** Avoiding the linting process, leading to a gradual degradation of i18n code quality. ## 2. Development Extensions and Environment Setup ### 2.1 IDE Plugins **Standard:** Utilize IDE plugins that provide i18n-specific features like syntax highlighting, string extraction, translation assistance, and locale management. **Do This:** * Install relevant plugins for your IDE of choice (e.g., VSCode, IntelliJ IDEA, Eclipse). * Configure the plugins to match your project's i18n settings and workflow. * Use the plugins to quickly identify and fix i18n-related code issues. **Don't Do This:** * Rely solely on default IDE features without installing specialized i18n plugins. * Fail to properly customize the plugin settings for optimal performance and accuracy. **Why:** IDE plugins enhance developer productivity by providing immediate feedback and assistance with i18n tasks. **Example:** VS Code with the "i18next Ally" extension provides excellent support for "i18next" based projects. ### 2.2 Build Tools **Standard:** Configure build tools to automate i18n-related tasks like resource file processing, locale data compilation, and translation validation. **Do This:** * Use tools like Webpack, Parcel, or Rollup to process locale files and optimize them for production. * Set up scripts to validate the integrity of translated resources and ensure all necessary translations are available. * Utilize build-time transformations to optimize i18n performance (e.g., pre-compiling message formats). **Don't Do This:** * Perform i18n-related tasks manually during the build process. * Include unnecessary locale data in production builds, increasing the application's size. **Why:** Automated build processes streamline i18n workflows, improve efficiency, and reduce the risk of deployment issues. **Code Example (Webpack configuration):** """javascript // webpack.config.js const path = require('path'); module.exports = { entry: './src/index.js', output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' }, module: { rules: [ { test: /\.json$/, type: 'javascript/module', use: { loader: 'json-loader' } } ] }, resolve: { extensions: ['.js', '.json'] } }; """ This example shows Webpack configured to handle ".json" files with the appropriate loader. Now you could import json language files directly. **Anti-Pattern:** Manual optimization of localized resources, leading to human error and inconsistent build configurations. ### 2.3 CI/CD Integration **Standard:** Integrate i18n checks and validations into the CI/CD pipeline to ensure every commit and release meets i18n quality standards. **Do This:** * Run linters, static analysis tools, and translation validators as part of the CI/CD process. * Fail the build if any i18n-related checks fail. * Automate the deployment of localized resources alongside the application code. **Don't Do This:** * Bypass i18n checks during the CI/CD process. * Manually deploy localized resources separately from the application. **Why:** CI/CD integration ensures that i18n quality is maintained throughout the entire development lifecycle, preventing regressions and deployment issues. **Example:** Setup in GitHub Actions. """yaml # .github/workflows/main.yml name: CI/CD Pipeline on: push: branches: - main jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Node.js uses: actions/setup-node@v3 with: node-version: 18 - name: Install dependencies run: npm install - name: Run linters run: npm run lint - name: Run tests run: npm run test:i18n - name: Build project run: npm run build - name: Deploy to production run: | # Add deployment steps here... echo "Deploying to production..." """ **Anti-Pattern:** Delaying i18n testing until late in the release cycle, resulting in costly rework and missed deadlines. ## 3. Security ### 3.1 Preventing Locale Injection **Standard:** Sanitize and validate user-provided locale information to prevent locale injection attacks. **Do This:** * Implement a whitelist of supported locales and check if user input matches an entry. * Avoid using user input directly in file paths or resource URLs. * Encode or escape user input used in message formatting to prevent code injection. **Don't Do This:** * Trust user-provided locale information without proper validation. * Construct file paths or resource URLs dynamically using user input without sanitization. **Why:** Locale injection attacks can allow malicious users to access sensitive information, execute arbitrary code, or cause denial-of-service. Proper validation and sanitization prevent these vulnerabilities. **Code Example (Locale validation):** """javascript const supportedLocales = ['en', 'fr', 'de']; function isValidLocale(locale) { return supportedLocales.includes(locale); } function setLocale(userProvidedLocale) { const locale = userProvidedLocale.trim().toLowerCase(); if (isValidLocale(locale)) { // Set application locale console.log("Setting locale to: ${locale}"); } else { console.error("Invalid locale: ${locale}"); // Fallback to default locale } } setLocale(' fr '); // Valid setLocale('ja'); // Invalid """ **Anti-Pattern:** Blindly trusting the "Accept-Language" header or URL parameters for locale determination, as these can be easily manipulated. ## 4. Performance Optimization ### 4.1 Lazy Loading of Locale Data **Standard:** Implement lazy loading of locale data to reduce the initial load time and memory footprint of the application. **Do This:** * Load locale data on demand when a specific locale is requested. * Use code splitting to separate locale data into smaller chunks that can be loaded independently. * Cache locale data in the browser to avoid repeated downloads. **Don't Do This:** * Load all locale data at application startup, increasing the initial load time. * Fail to cache downloaded locale data, resulting in excessive network requests. **Why:** Lazy loading and code splitting improve the performance of internationalized applications by reducing the amount of data that needs to be downloaded and processed upfront. **Example:** Code splitting using dynamic imports in JavaScript """javascript async function loadLocaleData(locale) { try { const data = await import("./locales/${locale}.json"); return data; } catch (error) { console.error("Failed to load locale data for ${locale}:", error); return null; } } async function initializeI18n(locale) { const localeData = await loadLocaleData(locale); if (localeData) { // Initialize i18n library with loaded data console.log("i18n initialized with ${locale} data"); } else { // Fallback strategy console.log('Fallback strategy in place.'); } } initializeI18n('fr'); """ **Anti-Pattern:** Bundling all locale-specific resources into one large Javascript bundle. ### 4.2 Caching Translated Messages **Standard:** Implement caching mechanisms to store frequently used translatedmessages, reducing the overhead of repeated formatting. **Do This:** * Cache translated messages in memory or in a distributed cache (e.g., Redis). * Use a cache key that includes the locale and the message ID. * Invalidate cache entries when translations are updated. **Don't Do This:** * Disable caching altogether, resulting in excessive formatting overhead. * Use overly aggressive caching strategies that prevent updates from being reflected. **Why:** Message caching improves the performance by reducing the time it takes to retrieve most commonly used translation. ### 4.3 Optimizing Resource Bundles **Standard:** Optimize the size and structure of localized resource bundles to minimize loading and parsing times. **Do This:** * Remove unused or redundant translations from resource bundles. * Compress resource bundles using gzip or Brotli. * Structure resource bundles in a way that allows for efficient lookup of translations **Don't Do This:** * Include unnecessary data in resource bundles, increasing their size. * Use inefficient data structures for storing translations, slowing down the lookup process. **Why:** Resource bundle optimization minimizes the amount of data that needs to be transferred and processed, reducing load times and improving application responsiveness. These standards ensure that tooling and ecosystems are leveraged effectively for Internationalization, enabling efficient, maintainable, secure, and high-performing applications. They should serve as a practical guide for developers and as a baseline for automated code analysis tools.
# Testing Methodologies Standards for Internationalization This document outlines the coding standards for testing methodologies in internationalized (i18n) applications. It provides guidelines for unit, integration, and end-to-end testing, ensuring that i18n features are correctly implemented and maintainable. These standards are designed for professional development teams and are applicable to AI coding assistants. ## 1. General Testing Principles for Internationalization ### 1.1 Character Encoding **Do This**: Ensure consistent character encoding (UTF-8) across the application. **Don't Do This**: Use different encodings in different parts of your application, which can lead to character corruption. **Why**: Maintaining consistent character encoding is crucial for displaying text correctly in different languages. UTF-8 supports a wide range of characters and is widely supported. """python # Example: Setting UTF-8 encoding for a Flask application from flask import Flask, render_template app = Flask(__name__) app.config['JSON_AS_ASCII'] = False # Ensure Unicode is not escaped @app.route('/') def index(): return render_template('index.html', message="你好，世界！") # Chinese "Hello, World!" """ ### 1.2 Locale Awareness **Do This**: Ensure your test environment mimics different locales. **Don't Do This**: Test only in a single, default locale. **Why**: Testing in multiple locales exposes issues related to date/time formats, number formats, and text direction. """python # Example: Testing number formatting in different locales (Python) import locale def format_number(number, locale_name): try: locale.setlocale(locale.LC_ALL, locale_name) return locale.format_string("%d", number, grouping=True) except locale.Error as e: print(f"Locale error: {e}") return str(number) # Fallback # Test with US locale print(format_number(1234567, "en_US.UTF-8")) # Output: 1,234,567 # Test with German locale print(format_number(1234567, "de_DE.UTF-8")) # Output: 1.234.567 """ ### 1.3 Text Expansion **Do This**: Account for text expansion in different languages during UI testing. **Don't Do This**: Design UI elements with fixed widths, as this can cause text overflow in some languages. **Why**: Text expansion can significantly impact UI layout. German, for example, often requires more space than English. """html <!-- Example: CSS to handle text overflow --> <div style="width: 200px; overflow: hidden; text-overflow: ellipsis;"> This is a long text that might overflow in certain languages. </div> """ ### 1.4 Bidirectional (Bidi) Text **Do This**: Test for proper handling of right-to-left (RTL) languages like Arabic and Hebrew. **Don't Do This**: Assume all text will always be left-to-right (LTR). **Why**: Bidi text requires special handling to ensure text is displayed correctly. """html <!-- Example: HTML with Bidi support --> <div dir="rtl"> مرحبا بالعالم </div> """ ### 1.5 Pluralization **Do This**: Test pluralization rules for different languages thoroughly. **Don't Do This**: Implement a simple "if count == 1 then singular else plural" rule. **Why**: Pluralization rules vary significantly between languages (some have singular, plural, dual, few, many, and other forms). """python # Example: Using gettext for pluralization import gettext import os # Set the locale directory localedir = os.path.join('.', 'locales') translate = gettext.translation('messages', localedir, languages=['fr']) translate.install() _ = translate.gettext def pluralize(n): return _('There is one apple') if n == 1 else _('There are {} apples').format(n) # Initialize gettext with locale and domain # Example usage print(pluralize(1)) print(pluralize(2)) # Ensure your .po files are correctly set up for each language """ ### 1.6 Collation **Do This**: Test sorting and searching using locale-specific collation rules. **Don't Do This**: Rely solely on ASCIIbetical sorting. **Why**: Collation rules differ between languages (e.g., accented characters, character order). """python # Example: Locale-aware sorting import locale locale.setlocale(locale.LC_ALL, 'de_DE.UTF-8') data = ['äpfel', 'bananen', 'apfel'] data.sort(key=locale.strxfrm) # Perform locale-aware comparison print(data) # ['apfel', 'äpfel', 'bananen'] """ ## 2. Unit Testing ### 2.1 Resource Bundle Loading **Do This**: Write unit tests to ensure resource bundles are loaded correctly for each locale. **Don't Do This**: Assume resource bundles will always load correctly without explicit testing. **Why**: Errors in resource bundle loading can lead to missing translations or application crashes. """java // Example: JUnit test for resource bundle loading import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; import java.util.ResourceBundle; import java.util.Locale; public class ResourceBundleTest { @Test public void testResourceBundleLoading() { Locale locale = new Locale("fr", "FR"); ResourceBundle bundle = ResourceBundle.getBundle("messages", locale); assertNotNull(bundle, "Resource bundle should not be null"); assertEquals("Bonjour le monde", bundle.getString("hello.world"), "Incorrect translation"); } @Test public void testResourceBundleFallback() { Locale locale = new Locale("es", "AR"); ResourceBundle bundle = ResourceBundle.getBundle("messages", locale); assertNotNull(bundle, "Resource bundle should not be null"); } } """ ### 2.2 Translation Function Correctness **Do This**: Unit test translation functions to verify they return the correct translated strings for given keys and locales. **Don't Do This**: Rely on manual verification of translations, as this is error-prone and time-consuming. """javascript // Example: Jest test for translation function const i18n = require('./i18n'); test('translates hello world to French', () => { i18n.setLocale('fr'); expect(i18n.translate('hello.world')).toBe('Bonjour le monde'); }); test('translates hello world to English', () => { i18n.setLocale('en'); expect(i18n.translate('hello.world')).toBe('Hello World'); }); """ ### 2.3 Pluralization Logic **Do This**: Provide comprehensive unit tests to verify pluralization logic for different languages. **Don't Do This**: Only test with English pluralization rules. **Why**: Pluralization rules vary between languages; thorough testing prevents display errors. """python # Example: Pytest for pluralization logic import pytest from your_i18n_module import pluralize def test_pluralize_english(): assert pluralize("apple", 0, locale="en") == "apples" assert pluralize("apple", 1, locale="en") == "apple" assert pluralize("apple", 2, locale="en") == "apples" def test_pluralize_french(): assert pluralize("apple", 0, locale="fr") == "pommes" assert pluralize("apple", 1, locale="fr") == "pomme" assert pluralize("apple", 2, locale="fr") == "pommes" """ ### 2.4 Date/Time Formatting **Do This**: Write unit tests for date/time formatting functions to ensure they produce the correct output for different locales. **Don't Do This**: Assume date/time formatting will always work correctly based on system settings. """java // Example: JUnit test for date formatting import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; import java.time.ZonedDateTime; import java.time.ZoneId; import java.time.format.DateTimeFormatter; import java.util.Locale; public class DateFormatTest { @Test public void testDateFormatting() { ZonedDateTime date = ZonedDateTime.of(2024, 10, 27, 10, 30, 0, 0, ZoneId.of("UTC")); Locale localeFR = new Locale("fr", "FR"); DateTimeFormatter formatterFR = DateTimeFormatter.ofPattern("dd/MM/yyyy HH:mm", localeFR); String formattedDateFR = date.format(formatterFR); assertEquals("27/10/2024 10:30", formattedDateFR, "Incorrect date format for French"); Locale localeDE = new Locale("de", "DE"); DateTimeFormatter formatterDE = DateTimeFormatter.ofPattern("dd.MM.yyyy HH:mm", localeDE); String formattedDateDE = date.format(formatterDE); assertEquals("27.10.2024 10:30", formattedDateDE, "Incorrect date format for German"); } } """ ## 3. Integration Testing ### 3.1 UI Integration with Locale Settings **Do This**: Verify that the UI correctly reflects locale settings, including date/time formats, number formats, and text direction. **Don't Do This**: Test UI elements in isolation without considering the overall locale context. **Why**: UI elements need to integrate with the locale settings to provide a consistent user experience. """python # Example: Selenium test for UI date formatting (Python) from selenium import webdriver from selenium.webdriver.common.by import By def test_ui_date_formatting(): driver = webdriver.Chrome() # Or any other browser driver.get("http://localhost:8000") # Replace with your app url # Set locale (e.g., via a dropdown) locale_dropdown = driver.find_element(By.ID, "locale-select") locale_dropdown.send_keys("fr-FR") # Check for date format date_element = driver.find_element(By.ID, "date-display") assert "27/10/2024" in date_element.text driver.quit() """ ### 3.2 Database Interactions **Do This**: Test database interactions to ensure that data is correctly stored and retrieved for different locales (especially considering collation). Persist data in UTF-8. **Don't Do This**: Assume database interactions will automatically handle different character sets correctly. **Why**: Incorrect database configurations can lead to data corruption or retrieval errors. """java // Example: JDBC integration test for character set handling import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; import java.sql.Connection; import java.sql.DriverManager; import java.sql.PreparedStatement; import java.sql.ResultSet; import java.sql.SQLException; public class DatabaseTest { @Test public void testCharacterSetHandling() throws SQLException { String url = "jdbc:mysql://localhost:3306/testdb?useUnicode=true&characterEncoding=utf8"; // MySQL specific String user = "user"; String password = "password"; try (Connection connection = DriverManager.getConnection(url, user, password)) { String insertQuery = "INSERT INTO i18n_test (text) VALUES (?)"; try (PreparedStatement insertStatement = connection.prepareStatement(insertQuery)) { insertStatement.setString(1, "你好，世界！"); // Chinese "Hello, World!" insertStatement.executeUpdate(); } String selectQuery = "SELECT text FROM i18n_test WHERE text = ?"; try (PreparedStatement selectStatement = connection.prepareStatement(selectQuery)) { selectStatement.setString(1, "你好，世界！"); try (ResultSet resultSet = selectStatement.executeQuery()) { assertTrue(resultSet.next(), "Data should be retrieved correctly"); assertEquals("你好，世界！", resultSet.getString("text"), "Incorrect data retrieved"); } } } } } """ ### 3.3 API Endpoint Localization **Do This**: Test API endpoints to ensure they return localized data based on the "Accept-Language" header. **Don't Do This**: Assume API endpoints will always return data in a single, default language. **Why**: API endpoints should support localization to provide a consistent experience across different clients. """python # Example: Using pytest and FastAPI to test Accept-Language header (Python) from fastapi import FastAPI from fastapi.testclient import TestClient app = FastAPI() @app.get("/greeting") async def greeting(request: Request): accept_language = request.headers.get("accept-language", "en-US") if "fr" in accept_language: return {"message": "Bonjour le monde"} else: return {"message": "Hello World"} client = TestClient(app) def test_greeting_french(): response = client.get("/greeting", headers={"accept-language": "fr-FR"}) assert response.status_code == 200 assert response.json() == {"message": "Bonjour le monde"} def test_greeting_english(): response = client.get("/greeting", headers={"accept-language": "en-US"}) assert response.status_code == 200 assert response.json() == {"message": "Hello World"} """ ## 4. End-to-End (E2E) Testing ### 4.1 User Flows in Different Locales **Do This**: Test complete user flows in different locales to ensure a seamless experience. **Don't Do This**: Focus solely on individual components without considering the overall user journey. **Why**: E2E testing validates that all parts of the application work correctly together in a localized context. """javascript // Example: Cypress test for user login flow in French describe('User Login Flow - French Locale', () => { beforeEach(() => { cy.visit('http://localhost:3000'); // Replace with your app URL cy.get('#locale-select').select('fr'); // Select French locale }); it('logs in successfully', () => { cy.get('#username').type('testuser'); cy.get('#password').type('password'); cy.get('#login-button').click(); cy.contains('Bienvenue, testuser').should('be.visible'); // Translated welcome message }); }); """ ### 4.2 Bidi Text Layout **Do This**: Perform E2E tests to ensure correct layout and rendering of Bidi text in RTL languages. **Don't Do This**: Exclude Bidi text from E2E testing. **Why**: Bidi text can cause layout issues if not handled correctly. """javascript // Example: Cypress test for RTL text layout describe('RTL Text Layout', () => { beforeEach(() => { cy.visit('http://localhost:3000'); cy.get('#locale-select').select('ar'); // Select Arabic/RTL Locale }); it('displays RTL text correctly', () => { cy.get('.rtl-text').should('have.attr', 'dir', 'rtl'); cy.get('.rtl-text').should('have.css', 'text-align', 'right'); }); }); """ ### 4.3 Dynamic Content Localization **Do This**: Test the localization of dynamically generated content (e.g., user-generated posts, comments). **Don't Do This**: Only test static, pre-translated content. **Why**: Dynamic content needs to be localized to provide a complete localized experience. """python # Example: Playwright test for dynamic content localization from playwright.sync_api import sync_playwright def test_dynamic_content_fr(): with sync_playwright() as p: browser = p.chromium.launch() page = browser.new_page() page.goto("http://localhost:3000") # Replace with your app's URL page.select_option("#locale-select", "fr") # Simulate user posting a comment page.fill("#comment-input", "Ceci est un commentaire") page.click("#submit-comment") # Verify that comment is displayed correctly and localized assert "Ceci est un commentaire" in page.inner_text("#comment-list") browser.close() """ ### 4.4 Error Message Localization **Do This**: Test all error messages to ensure they are correctly localized. **Don't Do This**: Overlook error messages in your localization efforts. **Why**: Localized error messages are essential for a good user experience. """javascript // Example: Selenium test for error message localization from selenium import webdriver from selenium.webdriver.common.by import By def test_localized_error_message(): driver = webdriver.Chrome() # Or any other browser driver.get("http://localhost:8000") # Replace with your app url # Set locale (e.g., via a dropdown) locale_dropdown = driver.find_element(By.ID, "locale-select") locale_dropdown.send_keys("fr-FR") # Trigger an error (e.g., submitting an invalid form) submit_button = driver.find_element(By.ID, "submit-button") submit_button.click() # Get the error message error_message = driver.find_element(By.ID, "error-message").text assert "Veuillez remplir tous les champs obligatoires" in error_message driver.quit() """ ## 5. Automated Testing Infrastructure ### 5.1 Continuous Integration (CI) **Do This**: Integrate i18n testing into your CI pipeline. This ensures that changes don't break localization. **Don't Do This**: Delay i18n testing until late in the development cycle. **Why**: Early and continuous testing catches i18n issues before they become costly to fix. """yaml # Example: GitHub Actions workflow for i18n testing (YAML) name: I18n Tests on: push: branches: [ main ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python 3.9 uses: actions/setup-python@v3 with: python-version: 3.9 - name: Install dependencies run: | python -m pip install --upgrade pip pip install pytest selenium # Add any other testing dependencies - name: Run i18n tests run: pytest -v tests/i18n_tests.py """ ### 5.2 Mocking and Stubbing **Do This**: Use mocking and stubbing to isolate i18n components during testing. **Don't Do This**: Rely on external services or live APIs during unit testing. **Why**: Mocking and stubbing make tests faster, more reliable, and easier to debug. """python # Example: Mocking gettext in a unit test from unittest.mock import patch from your_module import your_function @patch('your_module.gettext.translation') def test_your_function_fr(mock_translation): mock_translation.return_value.gettext.return_value = "Translated string" result = your_function(locale="fr") assert result == "Translated string" """ ### 5.3 Test Data Management **Do This**: Manage test data effectively, including localized strings, dates, and numbers. **Don't Do This**: Hardcode test data directly in your tests. **Why**: Test data should be maintainable, reusable, and representative of real-world scenarios. """json // Example: Test data for French locale { "locale": "fr-FR", "strings": { "hello.world": "Bonjour le monde", "welcome.message": "Bienvenue sur notre site web" }, "date_format": "dd/MM/yyyy", "number_format": "# ##0,00" } """ ## 6. Tooling and Libraries ### 6.1 i18next **Do This**: For JavaScript projects, use i18next along with its testing utilities for robust internationalization. **Don't Do This**: Roll your own custom solution without considering established and well-maintained libraries. **Why**: i18next provides a comprehensive i18n solution with features like pluralization, context-based translations, and locale fallbacks. """javascript // Example: i18next setup in a testing environment import i18next from 'i18next'; import { initReactI18next } from 'react-i18next'; i18next .use(initReactI18next) .init({ lng: 'en', // Default locale fallbackLng: 'en', resources: { en: { translation: { 'hello.world': 'Hello World', }, }, fr: { translation: { 'hello.world': 'Bonjour le monde', }, }, }, interpolation: { escapeValue: false, // React already escapes }, }); export default i18next; // In your test file: import i18n from './i18n'; test('translates hello world to French', () => { i18n.changeLanguage('fr'); expect(i18n.t('hello.world')).toBe('Bonjour le monde'); }); """ ### 6.2 Gettext **Do This**: Use gettext for Python and C-based projects. Gettext is a mature and widely used i18n library. **Don't Do This**: Avoid using gettext in projects where it is the standard i18n solution. **Why**: Gettext provides a standard way to manage translations. See code example in Pluralization section above. ## 7. Security Considerations ### 7.1 Preventing Injection Attacks **Do This**: Ensure that translated strings are properly sanitized to prevent injection attacks (e.g., XSS). **Don't Do This**: Trust that translated strings are always safe. **Why**: Malicious translations can compromise the security of your application. ### 7.2 Locale Spoofing **Do This**: Validate locale settings to prevent users from spoofing locales. **Don't Do This**: Trust user-provided locale settings without validation. **Why**: Locale spoofing can lead to unexpected behavior or security vulnerabilities. ### 7.3 UTF-8 Validation **Do This**: Validate UTF-8 encoding to prevent malformed characters. **Don't Do This**: Assume UTF-8 strings are always valid. **Why**: Malformed UTF-8 characters can cause display issues or security vulnerabilities. ## 8. Performance Optimization ### 8.1 Lazy Loading of Resource Bundles **Do This**: Load resource bundles lazily to improve application startup time. **Don't Do This**: Load all resource bundles upfront. **Why**: Loading all resource bundles upfront can slow down application startup. ### 8.2 Caching Translations **Do This**: Cache translations to reduce the overhead of looking up translations. **Don't Do This**: Look up translations every time they are needed without caching. **Why**: Caching can significantly improve the performance of translation lookups. ### 8.3 Test Performance with Different Locales **Do This**: Measure the performance of your application with different locales. **Don't Do This**: Assume performance will be the same across all locales. **Why**: Different locales can have different performance characteristics (e.g., due to text expansion or collation). ## 9. Code Review Checklist for Internationalization ### 9.1 General * [ ] All text displayed to the user is properly internationalized. * [ ] Date, time, number, and currency formats are locale-aware. * [ ] Text expansion and Bidi text are handled correctly. * [ ] Pluralization rules are correct for all supported languages. * [ ] Character encoding is consistent throughout the application (UTF-8). ### 9.2 Testing * [ ] Unit tests cover resource bundle loading, translation function correctness, and pluralization logic. * [ ] Integration tests verify UI integration with locale settings and database interactions. * [ ] End-to-end tests validate user flows in different locales and Bidi text layout. * [ ] Automated testing infrastructure includes i18n tests in the CI pipeline. ### 9.3 Security * [ ] Translated strings are properly sanitized to prevent injection attacks. * [ ] Locale settings are validated to prevent spoofing. * [ ] UTF-8 encoding is validated to prevent malformed characters. ### 9.4 Performance * [ ] Resource bundles are loaded lazily. * [ ] Translations are cached. * [ ] Application performance is measured with different locales. By following these standards, development teams can ensure that their applications are properly internationalized, maintainable, secure, and performant. This document acts as a guide for developers and can be used as context for AI coding assistants to generate high-quality i18n code.
# Core Architecture Standards for Internationalization This document outlines the core architectural standards for developing internationalized applications. These standards guide structural design, project organization, and coding practices to ensure applications are easily adaptable to different locales, languages, and cultural conventions. Following these standards leads to more maintainable, scalable, and user-friendly internationalized software. ## 1. Fundamental Architectural Patterns ### 1.1 Layered Architecture with I18n Concerns Segregated * **Do This:** Adopt a layered architecture (e.g., presentation, application, domain, infrastructure) and isolate internationalization concerns to specific layers or modules. This decouples I18n from core business logic, enhancing maintainability and testability. * **Don't Do This:** Sprinkle I18n-related code (e.g., string lookups, date formatting) throughout all layers of the application. This tightly couples I18n to application logic, creating a maintenance nightmare. * **Why:** Segregation of concerns allows independent evolution of I18n features without impacting the core application. It also simplifies testing and localization workflows. **Example (Java):** """java // Presentation Layer (using resource bundles) public class UserInterface { private ResourceBundle messages; public UserInterface(Locale locale) { messages = ResourceBundle.getBundle("messages", locale); } public void displayWelcomeMessage() { String welcomeMessage = messages.getString("welcome.message"); System.out.println(welcomeMessage); } } // Application Layer (orchestrates) public class ApplicationService { public void showWelcome(Locale locale) { UserInterface ui = new UserInterface(locale); ui.displayWelcomeMessage(); } } """ **Anti-Pattern:** """java // Anti-pattern: I18n logic directly embedded in the business logic. public class OrderService { public String createOrderConfirmation(Order order, Locale locale) { if (locale.getLanguage().equals("fr")) { return "Confirmation de commande : " + order.getOrderId(); } else { return "Order Confirmation: " + order.getOrderId(); } } } """ ### 1.2 Resource Bundle Management * **Do This:** Use resource bundles (or equivalent mechanisms like translation files in JSON or YAML) to externalize all localizable strings. Organize resource files using a consistent naming convention (e.g., "messages_en.properties", "messages_fr_CA.properties"). * **Don't Do This:** Hardcode strings directly into your codebase. This makes it extremely difficult to translate and support multiple languages. * **Why:** Resource bundles allow translators to work independently of developers, and they enable easy switching between locales at runtime. **Example (JavaScript/React with i18next):** """javascript // i18n.js (configuration) import i18n from 'i18next'; import { initReactI18next } from 'react-i18next'; import en from './locales/en/translation.json'; import fr from './locales/fr/translation.json'; i18n .use(initReactI18next) // passes i18n down to react-i18next .init({ resources: { en: { translation: en }, fr: { translation: fr } }, lng: "en", // default language fallbackLng: "en", interpolation: { escapeValue: false // react already safes from xss } }); export default i18n; // Component (using translation) import React from 'react'; import { useTranslation } from 'react-i18next'; function MyComponent() { const { t } = useTranslation(); return ( <h1>{t('welcome.title')}</h1> ); } export default MyComponent; //locales/en/translation.json { "welcome.title": "Welcome to our Application!" } //locales/fr/translation.json { "welcome.title": "Bienvenue dans notre application !" } """ ### 1.3 Locale Context Management * **Do This:** Centralize locale management using a "LocaleContext" (or equivalent) to propagate the current locale throughout the application. This ensures consistent formatting and string lookups. * **Don't Do This:** Access the locale directly from system settings or browser settings in multiple places. This creates inconsistencies and makes it hard to change the locale dynamically. * **Why:** A centralized locale context makes it easy to switch locales programmatically and maintain a consistent user experience. **Example (React Context API):** """javascript // LocaleContext.js import React, { createContext, useState, useContext } from 'react'; const LocaleContext = createContext(); export const LocaleProvider = ({ children }) => { const [locale, setLocale] = useState('en-US'); const updateLocale = (newLocale) => { setLocale(newLocale); }; return ( <LocaleContext.Provider value={{ locale, updateLocale }}> {children} </LocaleContext.Provider> ); }; export const useLocale = () => useContext(LocaleContext); // Usage in a component import React from 'react'; import { useLocale } from './LocaleContext'; function MyComponent() { const { locale } = useLocale(); return ( <div> Current Locale: {locale} </div> ); } """ ### 1.4 Unicode Support and Handling * **Do This:** Ensure the entire application stack (database, application server, client-side code) supports Unicode (UTF-8). Use Unicode-aware string functions and libraries. Normalize Unicode strings for consistent comparison and sorting. * **Don't Do This:** Rely on character encodings other than UTF-8. Use string functions that are not Unicode-aware. * **Why:** Unicode is essential for supporting a wide range of languages and characters. Inconsistent Unicode handling leads to data corruption, display issues, and incorrect sorting. **Example (Python):** """python # Correct usage of Unicode normalization import unicodedata def normalize_string(text): """Normalizes a Unicode string to NFC form.""" return unicodedata.normalize('NFC', text) string1 = "café" string2 = "cafe\u0301" # café with combining acute accent normalized_string1 = normalize_string(string1) normalized_string2 = normalize_string(string2) print(normalized_string1 == normalized_string2) # Output: True """ ### 1.5 Pluggable I18n Modules * **Do This:** Design your application with pluggable I18n modules or providers. This facilitates switching I18n libraries or services without major code refactoring. For example, using an interface that allows swapping out different number formatting implementations. * **Don't Do This:** Tightly couple your codebase to a specific I18n library. This creates a vendor lock-in and makes it difficult to migrate to another library in the future. * **Why:** Architectural flexibility makes for more resilient applications. **Example (C# with Dependency Injection):** """csharp // ILocalizationService Interface public interface ILocalizationService { string GetString(string key); } // Concrete Implementation public class ResourceBundleLocalizationService : ILocalizationService { private readonly ResourceSet resourceSet; public ResourceBundleLocalizationService(string baseName, CultureInfo culture) { resourceSet = ResourceSet.GetResourceSet(baseName,culture,true); //Added "true" to explicitly set the ResourceSet as not to be culture-neutral. } public string GetString(string key) { return resourceSet.GetString(key); } } // Application Code (using Dependency Injection) public class MyController { private readonly ILocalizationService _localizationService; public MyController(ILocalizationService localizationService) { _localizationService = localizationService; } public IActionResult Index() { ViewBag.WelcomeMessage = _localizationService.GetString("WelcomeMessage"); return View(); } } // Startup.cs (configuring DI) public void ConfigureServices(IServiceCollection services) { services.AddTransient<ILocalizationService>(provider => new ResourceBundleLocalizationService("MyResources", CultureInfo.CurrentCulture)); services.AddControllersWithViews(); } """ ## 2. Project Structure and Organization ### 2.1 Standardized Resource File Structure * **Do This:** Establish a clear and consistent directory structure for resource files. A common pattern is: "locales/<language>/<namespace>.json" (e.g., "locales/en/translation.json", "locales/fr/common.json"). * **Don't Do This:** Scatter resource files across the project without a clear organizational scheme. * **Why:** A well-defined directory structure streamlines the localization process, making it easy for translators and developers to locate and manage resource files. **Example (Node.js/Express):** """ project/ ├── locales/ │ ├── en/ │ │ ├── translation.json │ │ └── common.json │ ├── fr/ │ │ ├── translation.json │ │ └── common.json │ └── de/ │ ├── translation.json │ └── common.json ├── src/ │ ├── ... ├── package.json └── ... """ ### 2.2 Modular Resource Bundles * **Do This:** Divide resource files into smaller, module-specific bundles (e.g., "user.json", "product.json") rather than having a single, massive "messages.json" file. * **Don't Do This:** Place all strings for the entire application into one large resource bundle. * **Why:** Modular resource bundles improve maintainability, reduce merge conflicts, and allow for lazy loading of translations. **Example (JavaScript/React):** """javascript // src/components/UserComponent.js import { useTranslation } from 'react-i18next'; function UserComponent() { const { t } = useTranslation('user'); // namespace 'user' return ( <div> <p>{t('profile.greeting')}</p> </div> ); } export default UserComponent; // locales/en/user.json { "profile.greeting": "Hello, User!" } // locales/fr/user.json { "profile.greeting": "Bonjour, Utilisateur !" } // i18n.js (Configuration example): import i18n from 'i18next'; import { initReactI18next } from 'react-i18next'; import Backend from 'i18next-http-backend'; import LanguageDetector from 'i18next-browser-languagedetector'; i18n .use(Backend) .use(LanguageDetector) .use(initReactI18next) .init({ fallbackLng: 'en', debug: true, ns: ['translation', 'user'], // load namespaces defaultNS: 'translation', backend: { loadPath: '/locales/{{lng}}/{{ns}}.json', }, interpolation: { escapeValue: false, // not needed for react as it escapes by default } }); export default i18n; """ ### 2.3 Version Control Strategies for Translations * **Do This:** Incorporate resource files into your version control system (e.g., Git) alongside code. Use branches or tags to manage different versions of translations. Ideally integrate with a translation management system (TMS). * **Don't Do This:** Exclude resource files from version control, or manage them separately. * **Why:** Version control of translations ensures that changes are tracked, conflicts can be resolved, and you can revert to previous versions if needed. ### 2.4 Separation of Concerns: Code and Content * **Do This:** Strive to keep translatable content (*what* is said) separate from the code that displays it (*how* it is displayed). Use templating engines or UI frameworks with built-in I18n support to manage content presentation. * **Don't Do This:** Embed content directly within code logic, particularly UI-related code. * **Why:** Separation of concerns benefits both translators and developers, as it permits independent workflow. **Example (Angular):** """html <!-- Component Template --> <h1>{{ 'WELCOME_MESSAGE' | translate }}</h1> // Component.ts import { Component } from '@angular/core'; import { TranslateService } from '@ngx-translate/core'; @Component({ selector: 'app-my-component', templateUrl: './my-component.component.html', styleUrls: ['./my-component.component.css'] }) export class MyComponent { constructor(private translate: TranslateService) { translate.setDefaultLang('en'); translate.use('en'); } } // en.json { "WELCOME_MESSAGE": "Welcome to our application!" } // fr.json { "WELCOME_MESSAGE": "Bienvenue dans notre application !" } """ ### 2.5 Testing Internationalization * **Do This:** Integrate I18n testing into your CI/CD pipeline. Test with different locales, character sets, and date/time formats. Use pseudo-localization (e.g., replacing characters with their accented equivalents) to identify hardcoded strings and layout issues. * **Don't Do This:** Neglect I18n testing or treat it as an afterthought. * **Why:** Early I18n testing helps identify and fix issues before they reach production, reducing the cost of remediation. **Example (Pseudo-localization in JavaScript):** """javascript function pseudolocalize(text) { // Replace characters with accented equivalents and add brackets const localizedText = "[" + text.replace(/[aeiou]/gi, (match) => { switch (match.toLowerCase()) { case 'a': return 'à'; case 'e': return 'é'; case 'i': return 'î'; case 'o': return 'ô'; case 'u': return 'ü'; default: return match; } }) + "]"; return localizedText; } const originalText = "Hello world"; const pseudoLocalizedText = pseudolocalize(originalText); console.log(pseudoLocalizedText); // Output: [Héllô wôrld] //This identifies if UI elements overflow when using strings in other languages with different length, and possible hardcoded strings. """ ## 3. Modern Approaches and Patterns ### 3.1 ICU Message Format * **Do This:** Use the ICU Message Format for handling complex pluralization, gender agreement, and selection based on other parameters. * **Don't Do This:** Rely on simple if/else statements or string concatenation for handling pluralization and other grammatical variations. * **Why:** ICU Message Format provides a standardized and powerful way to handle complex localization scenarios, avoiding the need for ad-hoc string manipulation. **Example (JavaScript with "intl-messageformat"):** """javascript import { IntlMessageFormat } from 'intl-messageformat'; const messages = { en: { itemCount: '{count, plural, =0 {No items} one {1 item} other {# items}}' }, fr: { itemCount: '{count, plural, =0 {Aucun article} one {1 article} other {# articles}}' } }; const locale = 'fr'; const count = 3; const message = new IntlMessageFormat(messages[locale].itemCount, locale); const formattedMessage = message.format({ count }); console.log(formattedMessage); // Output: 3 articles """ ### 3.2 Translation Management Systems (TMS) Integration * **Do This:** Integrate your application development process with a Translation Management System (TMS) to streamline translation workflows, manage terminology, and ensure translation quality. * **Don't Do This:** Manually manage translation files or rely on email-based communication for translations. * **Why:** TMS integration automates the translation process, reduces errors, and improves collaboration between developers and translators. ### 3.3 Machine Translation (MT) and Post-Editing * **Do This:** Consider using Machine Translation (MT) as a starting point for translations, followed by human post-editing to ensure accuracy and quality. Be aware of the limitations of MT and use it judiciously. * **Don't Do This:** Rely solely on MT without human review, especially for critical content. * **Why:** MT can significantly speed up the translation process, but human post-editing is essential for ensuring accuracy and maintaining brand voice. ### 3.4 Server-Side vs. Client-Side Localization * **Do This:** Determine whether localization should be performed on the server-side or client-side based on performance requirements, SEO considerations, and user experience. Server-side localization improves SEO and initial load time, while client-side localization allows for dynamic language switching without page reloads. * **Don't Do This:** Assume one approach is always best for all situations. * **Why:** Choosing the right localization strategy can optimize performance and enhance the user experience. ### 3.5 Content Delivery Networks (CDNs) for Localized Assets * **Do This:** Use CDNs to distribute localized assets (e.g., images, videos, CSS files) to users based on their geographic location. * **Don't Do This:** Serve all assets from a single server, regardless of user location. * **Why:** CDNs improve performance by reducing latency and bandwidth consumption. By adhering to these architectural standards, development teams can build internationalized applications that are robust, maintainable, and adaptable to a global audience.
# Component Design Standards for Internationalization This document outlines the coding standards for component design related to internationalization (i18n). It provides guidelines for creating reusable, maintainable, and scalable components that can be easily adapted to different locales. The document emphasizes modern approaches and best practices. ## 1. Principles of I18n-Aware Component Design ### 1.1 Abstraction and Separation of Concerns **Standard:** Localizable content should be abstracted away from the component's core logic. Components should not contain hardcoded text or locale-specific formatting. These concerns need to be separated, typically using resource bundles or translation files. **Why:** Prevents code clutter, makes it easier to manage and update translations, and promotes reusability. **Do This:** * Use resource bundles/translation files to store localizable content. * Load the appropriate resource bundle based on the current locale. * Pass the translated text as props (or use a context/hook) to the component. **Don't Do This:** * Hardcode text within component templates. * Perform locale-specific formatting directly in the component. **Example (React):** """jsx // i18n/locales/en.json { "greeting": "Hello, {name}!" } // i18n/locales/fr.json { "greeting": "Bonjour, {name} !" } // i18n.js (example using i18next) import i18n from 'i18next'; import { initReactI18next } from 'react-i18next'; import en from './locales/en.json'; import fr from './locales/fr.json'; i18n .use(initReactI18next) // passes i18n down to react-i18next .init({ resources: { en: { translation: en }, fr: { translation: fr } }, lng: "en", // default language fallbackLng: "en", interpolation: { escapeValue: false // react already safes from xss } }); export default i18n; // Greeting.jsx import React from 'react'; import { useTranslation } from 'react-i18next'; function Greeting({ name }) { const { t } = useTranslation(); return <h1>{t('greeting', { name })}</h1>; } export default Greeting; // App.jsx import React from 'react'; import Greeting from './Greeting'; import './i18n'; // Initialize i18next function App() { return ( <div> <Greeting name="World" /> </div> ); } export default App; """ ### 1.2 Component Reusability for Different Locales **Standard:** Design components to be generic enough to accommodate different languages and cultural conventions without requiring modification of the component's code. **Why:** Reduces code duplication, simplifies maintenance, and ensures consistency across the application. **Do This:** * Parameterize components to accept locale-specific data (e.g., date/time formats, currency symbols). * Use CSS to handle text direction (LTR/RTL) and layout adjustments. * Avoid hardcoding assumptions about text length or character sets. **Don't Do This:** * Create separate components for each locale. * Use inline styles that conflict with RTL layouts. **Example (React with "react-intl"):** """jsx import React from 'react'; import { FormattedDate } from 'react-intl'; function EventDate({ timestamp, locale }) { return ( <p> <FormattedDate value={timestamp} year="numeric" month="long" day="numeric" locale={locale} /> </p> ); } export default EventDate; """ ### 1.3 Decoupling Content from Presentation **Standard:** Separate content (text, images, videos) from the way it is presented on the screen. Use styling and templating to determine appearance, independent of the content itself. **Why:** Ensures that changes to content don't require changes to the code and vice versa. **Do This:** * Utilize template engines or UI frameworks appropriately to minimize direct manipulation of the DOM. * Structure content in a data-oriented format (e.g., JSON, YAML). * Implement styling using CSS or CSS-in-JS libraries for dynamic adaptation. **Don't Do This:** * Embed content directly within JavaScript code. * Use JavaScript to directly manipulate element styles for content changes. ### 1.4 Handling Pluralization **Standard:** Use libraries or built-in i18n features to handle pluralization rules, which vary significantly across languages. **Why:** Ensures grammatically correct messages for different quantities. **Do This:** * Employ libraries designed for pluralization (e.g., "i18next", "messageformat"). * Define pluralization rules in resource bundles. **Don't Do This:** * Use simple "if/else" statements based on a single quantity - languages vary. **Example (i18next with pluralization):** """json // i18n/locales/en.json { "itemCount_zero": "No items", "itemCount_one": "One item", "itemCount_other": "{{count}} items" } // i18n/locales/fr.json { "itemCount_zero": "Aucun élément", "itemCount_one": "Un élément", "itemCount_other": "{{count}} éléments" } // Component import React from 'react'; import { useTranslation } from 'react-i18next'; function ItemList({ count }) { const { t } = useTranslation(); return <p>{t('itemCount', { count })}</p>; } export default ItemList; //Usage: <ItemList count={0} />, <ItemList count={1} />, <ItemList count={5} /> """ ### Performance Optimizations **Standard:** Implement strategies to optimize the loading and rendering of locale-specific resources. **Why:** Improves application responsiveness and reduces the initial load time. **Do This:** * **Code Splitting:** Load language resources only when needed, using dynamic imports or lazy loading. * **Caching:** Cache translated content and formatted data to avoid redundant computations. * **Content Delivery Networks (CDNs):** Deliver locale-specific assets from CDNs to reduce latency. * **Resource Bundling:** Bundle translation files into smaller, more manageable chunks. **Don't Do This:** * Load all language resources upfront during application startup. * Skip caching, resulting in slow rendering for the user. ## 2. Technology-Specific Considerations ### 2.1 React * **"react-intl" vs "i18next":** "react-intl" provides extensive formatting capabilities and internationalization support, adhering closely to the ECMAScript Internationalization API, but can add some complexity. "i18next" is very flexible, and has a large plugin ecosystem. Use the library which best aligns with your project's long term needs. ### 2.2 Vue.js * **"vue-i18n":** The official Vue.js internationalization plugin provides reactive translation management and locale formatting. Use formatter functions for complex interpolation scenarios. ### 2.3 Angular * **"@ngx-translate/core":** A popular library that seamlessly integrates translation workflows with Angular. Use Ahead-of-Time (AOT) compilation to optimize translation performance by pre-compiling translations during the build process. ## 3. Key Anti-Patterns ### 3.1 String Concatenation for Translations **Anti-Pattern:** """javascript function MyComponent({ name }) { const greeting = "Hello, " + name + "!"; // NO! return <h1>{greeting}</h1>; } """ **Why:** * Breaks easily with different word orders in other languages. * Difficult to maintain grammatically correct translations. **Solution:** Use placeholders or variables within translation strings. """json // en.json { "greeting": "Hello, {name}!" } """ """jsx import React from 'react'; import { useTranslation } from 'react-i18next'; function MyComponent({ name }) { const { t } = useTranslation(); return <h1>{t('greeting', { name })}</h1>; } """ ### 3.2 Hardcoding Date/Time Formats **Anti-Pattern:** """javascript function formatDate(date) { return date.getMonth() + 1 + "/" + date.getDate() + "/" + date.getFullYear(); //NO! } """ **Why:** Date/time formats vary drastically across locales. **Solution:** Use "Intl.DateTimeFormat" or appropriate formatting components. """javascript import { useIntl, FormattedDate } from 'react-intl'; function MyComponent({ date }) { const { locale } = useIntl(); return ( <p> <FormattedDate value={date} year="numeric" month="long" day="numeric" locale={locale} /> </p> ); } """ ### 3.3 Assuming Single Pluralization Rules **Anti-Pattern:** """javascript function getItemLabel(count) { if (count === 1) { return "item"; } else { return "items"; } // NO! - Insufficient for many languages } """ **Why:** Many languages have more complex pluralization rules than simple singular/plural. **Solution:** Use an i18n library with pluralization support. See examples in section 1.4. ### 3.4 Ignoring Text Direction (RTL/LTR) **Anti-Pattern:** Assuming all languages are LTR. **Why:** User interfaces appear broken and unintuitive when text direction is reversed. **Solution:** Implement CSS styles to dynamically handle text direction: """css .container { direction: ltr; /* Default */ } [dir="rtl"] .container { direction: rtl; /* Override for RTL locales */ } """ ## 4. Linting and Validation **Standard:** Integrate linting tools and validation scripts into the development process. They will help enforce i18n-related coding standards. **Why:** Ensures consistent application of i18n best practices and reduces the risk of introducing errors. **Do This:** * Use linters (e.g., ESLint with i18n-specific plugins) to detect hardcoded text and enforce naming conventions. * Create custom validation scripts to check for missing translations and unused translation keys. * Automate linting and validation as part of the build pipeline. **Example (ESLint with "eslint-plugin-i18n-json"):** """javascript // .eslintrc.js module.exports = { plugins: ['i18n-json'], rules: { 'i18n-json/valid-message-syntax': ['error'], 'i18n-json/sorted-keys': ['warn', 'asc', { caseSensitive: false }] } }; """ ## 5. Continuous Integration **Standard:** Integrate i18n-related checks into the CI/CD pipeline. Create automated tasks to verify resource integrity, translation completeness, and code compliance with established guidelines. **Why:** Continuous validation is essential for identifying potential issues early in the development lifecycle. **Do This:** * Create automated tests to verify the correct loading and rendering of locale-specific content. * Integrate linters and validation scripts as part of the CI/CD pipeline to automatically detect i18n-related issues. * Use monitoring tools to track i18n-related performance metrics in production. ## 6. Security Considerations ### 6.1 Preventing Cross-Site Scripting (XSS) **Standard:** Sanitize all user-provided translated content and properly escape data before rendering it. **Why:** Protects the application against XSS attacks, where malicious code is injected into the UI. **Do This:** * Use templating engines or UI frameworks that provide automatic escaping mechanisms. * Sanitize HTML content using libraries like DOMPurify if you need to allow some HTML while avoiding XSS. **Don't Do This:** * Directly render potentially unsafe HTML from translation files without proper sanitization. ## 7. Localization Vendor Integration To facilitate collaboration with localization vendors, the following guidelines should be followed: * **Standardized file formats:** Use industry-standard formats like ".xlf", ".json", or ".po" for translation files. * **Translation key stability:** Avoid changing translation keys unnecessarily as it forces translators to retranslate content which has already been created. Use automated tools to identify unused translation keys. * **Contextual information for translators:** Provide clear comments or descriptions for each translation key. Document the part of the application where this text appears, and the intended usage / meaning. This is extremely valuable so that translators can produce the most accurate output, and can greatly reduce the number of content revisions which would be needed otherwise. * **Platform:** Use translation management platforms (e.g., Phrase, Lokalise, Transifex) to streamline the translation process. ## 8. Testing **Standard:** Comprehensive testing is critical for successful internationalization of components. **Why:** Testing ensures that the components function reliably and correctly across different locales. **Do This:** * **Unit Tests:** Verify that the formatting logic correctly renders the components in different locales. * **End-to-End (E2E) Tests:** Simulate user interactions with the component and validate that localized content is displayed correctly. * **Linguistic Testing:** Use professional linguists or native speakers to review the translated content for accuracy, grammar, and tone. This is critical for ensuring the quality of the localized user experience. ## 9. Documentation **Standard:** Create and maintain comprehensive documentation for all i18n-related components and processes. **Why:** Ensures that developers, translators, and other stakeholders can easily understand and work with the codebase. **Do This:** * Document the purpose, usage, and limitations of each i18n-aware component. * Describe the process for adding new locales and updating translations. * Provide clear examples of how to use the components in different locales. * Maintain up-to-date documentation for any i18n-related libraries or tools used in the project.
# State Management Standards for Internationalization This document outlines the coding standards for managing state in applications with Internationalization (i18n) in mind. It guides developers to adopt best practices for handling localized data, including text, numbers, dates, currencies, and other culturally sensitive information. This document helps improve the maintainability, scalability, and performance of i18n-aware applications. ## 1. Introduction to i18n State Management Effective state management is crucial for applications with i18n requirements. It involves organizing, storing, and updating localized data, ensuring that the UI reflects the correct language and cultural conventions. Modern applications increasingly rely on reactive state management solutions to efficiently update the UI when locale or content changes. ### 1.1 Importance of Centralized State Centralizing i18n-related state offers several advantages: * **Consistency**: Ensures a consistent i18n experience across the application. * **Maintainability**: Simplifies updating or modifying i18n data, improving code maintainability. * **Performance**: Facilitates efficient data caching and retrieval, optimizing performance. ### 1.2 Types of i18n State i18n state typically includes: * **Current Locale**: The active locale selected by the user (e.g., "en-US", "fr-CA"). * **Translation Messages**: A dictionary of translated strings for different locales. * **Number and Date Formats**: Locale-specific formatting rules. * **Currency Information**: Symbols, positions, and decimal separators. ## 2. Core Principles for Managing i18n State ### 2.1 Single Source of Truth **Principle**: Maintain a single, authoritative source for all i18n-related data. **Why**: Prevents inconsistencies and simplifies state updates. **Do This**: Use a centralized state management solution (e.g., Redux, Vuex, Zustand, React Context) to store i18n data. **Don't Do This**: Avoid scattering i18n data across components or modules. **Example (React with Context):** """jsx // I18nContext.js import React, { createContext, useState, useEffect, useContext } from 'react'; import en from './translations/en.json'; import fr from './translations/fr.json'; const I18nContext = createContext(); const translations = { en: en, fr: fr, }; export const I18nProvider = ({ children }) => { const [locale, setLocale] = useState(localStorage.getItem('locale') || 'en'); // Load from localStorage or default to 'en' const [messages, setMessages] = useState(translations[locale]); useEffect(() => { localStorage.setItem('locale', locale); // Store locale in localStorage setMessages(translations[locale]); // Update messages when locale changes }, [locale]); const t = (key) => { return messages[key] || key; // Fallback to the key if translation is missing }; const value = { locale, setLocale, t, }; return ( <I18nContext.Provider value={value}> {children} </I18nContext.Provider> ); }; export const useI18n = () => useContext(I18nContext); // App.js import React from 'react'; import { I18nProvider, useI18n } from './I18nContext'; const Home = () => { const { t, locale, setLocale } = useI18n(); return ( <div> <h1>{t('greeting')}</h1> <p>{t('description')}</p> <button onClick={() => setLocale(locale === 'en' ? 'fr' : 'en')}> {t('changeLocale')} </button> </div> ); }; const App = () => { return ( <I18nProvider> <Home /> </I18nProvider> ); }; export default App; """ In this example: * "I18nContext" stores the current locale and translation messages. * "I18nProvider" provides these values to its children. * "useI18n" is a custom hook for accessing the context. * The locale is persisted in local storage. * The "t" function handles translation lookups, using a key-based approach. ### 2.2 Immutability **Principle**: Treat i18n state as immutable. **Why**: Simplifies state change detection and improves debugging. Makes state predictable. **Do This**: When updating i18n state, create a new state object instead of modifying the existing one. **Don't Do This**: Directly modify the i18n state object. **Example (React with useState):** """jsx import React, { useState } from 'react'; function LocaleSwitcher() { const [locale, setLocale] = useState('en-US'); const changeLocale = (newLocale) => { // DO THIS: Create a new state object setLocale(newLocale); // DON'T DO THIS: Mutate the existing state // locale = newLocale; // This is an anti-pattern in React }; return ( <div> <p>Current Locale: {locale}</p> <button onClick={() => changeLocale('fr-CA')}>Switch to French (Canada)</button> <button onClick={() => changeLocale('de-DE')}>Switch to German (Germany)</button> </div> ); } """ ### 2.3 Reactivity **Principle**: Ensure that UI components react automatically to changes in i18n state. **Why**: Keeps the UI consistent with the current locale and data. **Do This**: Use reactive state management solutions (e.g., React Context, Redux, Vuex, Zustand) to connect UI components to the i18n state. **Don't Do This**: Manually update UI components when i18n data changes. **Example (React with Context - continued from above):** The "Home" component automatically re-renders when the "locale" state changes, thanks to the "useI18n" hook and the "I18nContext". No manual updates are needed. ### 2.4 Lazy Loading Translations **Principle**: Load translation messages only when they are needed. **Why**: Improves initial load time and reduces memory usage. Optimizes the loading of heavy translation files. **Do This**: Use dynamic imports or code splitting to load translation files based on the current locale. **Don't Do This**: Load all translation files at application startup. **Example (Dynamic Imports in React):** """jsx import React, { useState, useEffect, createContext, useContext } from 'react'; const I18nContext = createContext(); export const I18nProvider = ({ children }) => { const [locale, setLocale] = useState(localStorage.getItem('locale') || 'en'); const [messages, setMessages] = useState({}); const [loading, setLoading] = useState(true); useEffect(() => { setLoading(true); import("./translations/${locale}.json") // Dynamic import .then((module) => { setMessages(module.default); setLoading(false); }) .catch((error) => { console.error("Failed to load translations:", error); setMessages({}); // Set to empty object to avoid errors setLoading(false); }); localStorage.setItem('locale', locale); }, [locale]); const t = (key) => { return messages[key] || key; // Fallback }; const value = { locale, setLocale, t, loading, }; return ( <I18nContext.Provider value={value}> {loading ? <div>Loading...</div> : children} </I18nContext.Provider> ); }; export const useI18n = () => useContext(I18nContext); """ In this example, the translation file for the current locale is loaded dynamically using "import()". A loading state ensures that components don't try to render before the translations are ready. ### 2.5 Locale Detection **Principle**: Automatically detect the user's preferred locale. **Why**: Provides a better user experience by presenting content in the user's language. **Do This**: * Use the "navigator.language" property in the browser. * Check the "Accept-Language" header on the server side. * Allow the user to override the detected locale. * Persist the user's choice in local storage or cookies. **Don't Do This**: * Rely solely on IP address geolocation (inaccurate and privacy concerns.) * Force users into a specific locale without providing an option to change it. **Example (Detecting and Setting Locale):** """javascript function detectLocale() { // Check local storage first const storedLocale = localStorage.getItem('locale'); if (storedLocale) { return storedLocale; } // Detect browser language const browserLocale = navigator.language || navigator.userLanguage; //userLanguage is for IE if (browserLocale) { return browserLocale; // This may need sanitization and validation } return 'en-US'; // Default locale } // Usage in the I18nProvider: import React, { createContext, useState, useEffect, useContext } from 'react'; // ... (I18nContext definition) export const I18nProvider = ({ children }) => { const [locale, setLocale] = useState(detectLocale()); // rest of the provider } """ This example first checks localStorage for a previously selected locale. If not found, it uses the browser's language settings. Error conditions should be handled, e.g., when an unsupported language is detected. The determined locale becomes the initial state. ### 2.6 Managing Fallbacks **Principle**: Implement a fallback mechanism for missing translations. **Why**: Ensures that the application remains functional even if some translations are not available for a specific locale. **Do This**: * Have a default locale (e.g., "en-US") that contains all translation keys and values. * Implement a fallback chain (e.g., if "fr-CA" is missing a key, fall back to "fr", then to "en-US"). * Display a warning or error message in development mode when a translation is missing. **Don't Do This**: * Display untranslated keys to the user in production. * Fail silently when a translation is missing. **Example (Translation Fallback Function):** """javascript const translations = { 'en-US': { 'greeting': 'Hello', 'description': 'Welcome to our website.', }, 'fr': { 'greeting': 'Bonjour' } }; function translate(key, locale) { const localeTranslations = translations[locale]; if (localeTranslations && localeTranslations[key]) { return localeTranslations[key]; } const baseLocale = locale.split('-')[0]; // fallback to the language code const baseLocaleTranslations = translations[baseLocale]; if (baseLocaleTranslations && baseLocaleTranslations[key]) { return baseLocaleTranslations[key]; } const defaultTranslations = translations['en-US']; // Fallback to en-US if (defaultTranslations && defaultTranslations[key]) { return defaultTranslations[key]; } console.warn("Missing translation for key "${key}" in locale "${locale}""); return key; // Return the key as a last resort } // Usage: console.log(translate('greeting', 'fr-CA')); // Output: Bonjour console.log(translate('description', 'fr-CA')); // Output: Welcome to our website. console.log(translate('missingKey', 'fr-CA')); // Output: missingKey (and a warning in the console) """ This "translate" function implements a fallback chain: locale-specific, language-specific, and then the default "en-US" locale. It also logs a warning to the console for missing translations, which is helpful during development. ## 3. State Management Libraries and Frameworks ### 3.1 React Context API **Description**: React's built-in context API allows you to share state between components without having to pass props manually at every level. **Pros**: * Simple and lightweight * No external dependencies * Easy to use for small to medium-sized applications **Cons**: * Not optimized for frequent updates in large applications (potential performance issues) * Lacks advanced features like middleware and devtools **Best Use Cases**: Managing locale and simple translation messages in smaller React applications. **Example**: (See Section 2.1) ### 3.2 Redux **Description**: A predictable state container for JavaScript apps. **Pros**: * Centralized state management * Predictable state changes * Middleware support for handling asynchronous actions * DevTools for debugging **Cons**: * More complex setup and boilerplate code * Can be overkill for small applications **Best Use Cases**: Large, complex applications with many components and frequent state updates. **Example (Redux with React):** """javascript // i18nActions.js export const SET_LOCALE = 'SET_LOCALE'; export const setLocale = (locale) => ({ type: SET_LOCALE, payload: locale, }); // i18nReducer.js const initialState = { locale: 'en-US', messages: {}, }; const i18nReducer = (state = initialState, action) => { switch (action.type) { case SET_LOCALE: return { ...state, locale: action.payload, }; default: return state; } }; export default i18nReducer; // store.js import { configureStore } from '@reduxjs/toolkit'; import i18nReducer from './i18nReducer'; const store = configureStore({ reducer: { i18n: i18nReducer, }, }); export default store; // App.js import React, { useEffect } from 'react'; import { useDispatch, useSelector } from 'react-redux'; import { setLocale } from './i18nActions'; import { loadTranslations } from './translationService'; // Assume this function fetches translations import { I18nextProvider } from 'react-i18next'; import i18n from './i18n'; // your i18next instance function App() { const dispatch = useDispatch(); const locale = useSelector((state) => state.i18n.locale); useEffect(() => { i18n.changeLanguage(locale); // set i18next language when locale changes }, [locale]); const changeLocale = (newLocale) => { dispatch(setLocale(newLocale)); }; return ( <div> <p>Current Locale: {locale}</p> <button onClick={() => changeLocale('fr-CA')}>Switch to French (Canada)</button> <button onClick={() => changeLocale('de-DE')}>Switch to German (Germany)</button> </div> ); } export default App; """ This example demonstrates a basic Redux setup for i18n: 1. **Actions**: "setLocale" is an action creator to update the locale. 2. **Reducer**: "i18nReducer" handles the "SET_LOCALE" action. Note: In a real application, this reducer would probably also handle loading translation messages. 3. **Store**: Configures the Redux store with the "i18nReducer". 4. **Component**: "App" uses "useDispatch" and "useSelector" to interact with the Redux store and trigger locale changes. This component uses i18next to perform translation, based on the locale loaded into Redux. ### 3.3 Zustand **Description**: A small, fast and scalable bearbones state-management solution using simplified flux principles. It is unopinionated and doesn't wrap your components in providers. **Pros**: * Minimal boilerplate * Easy to learn * Good performance **Cons**: * Less mature ecosystem compared to Redux. * Fewer advanced features (middleware, devtools). **Best Use Cases**: Medium-sized applications where simplicity and performance are crucial. **Example (Zustand):** """javascript import create from 'zustand'; const useI18nStore = create((set) => ({ locale: 'en-US', messages: {}, setLocale: (newLocale) => set({ locale: newLocale }), setMessages: (newMessages) => set({ messages: newMessages }), })); // Usage import React, { useEffect } from 'react'; import useI18nStore from './i18nStore'; import { loadTranslations } from './translationService'; // Assume this function fetches translations import { I18nextProvider } from 'react-i18next'; import i18n from './i18n'; // your i18next instance function App() { const { locale, setLocale } = useI18nStore(); useEffect(() => { i18n.changeLanguage(locale); // set i18next language when locale changes }, [locale]); const changeLocale = (newLocale) => { setLocale(newLocale); }; return ( <div> <p>Current Locale: {locale}</p> <button onClick={() => changeLocale('fr-CA')}>Switch to French (Canada)</button> <button onClick={() => changeLocale('de-DE')}>Switch to German (Germany)</button> </div> ); } export default App; """ This example demonstrates a basic Zustand setup for i18n. The "useI18nStore" hook provides access to the "locale", "messages", "setLocale", and "setMessages" state and actions. The component renders translated text using i18next. Note the minimal boilerplate required, making Zustand a lean alternative to Redux in many situations. ### 3.4 Choosing a Solution Here's a table summarizing factors to consider: | Feature | React Context | Redux | Zustand | | ---------------- | ------------- | -------- | --------- | | Complexity | Low | High | Medium | | Boilerplate | Low | High | Low | | Performance | Good (small) | Good | Excellent | | Scalability | Limited | Excellent | Good | | Use Cases | Simple apps | Complex apps| Medium apps | ## 4. Data Fetching and Caching ### 4.1 Fetching Translations **Standard**: Asynchronously fetch translation files from a server or local storage when the locale changes. **Why**: Improves performance by loading only the necessary translations. **Do This**: Use "fetch" or "axios" to load JSON files containing translations. Cache the fetched translations to avoid redundant requests. **Don't Do This**: Include all translations in the initial bundle. **Example (Fetching Translations):** """javascript async function loadTranslations(locale) { try { const response = await fetch("/locales/${locale}.json"); if (!response.ok) { throw new Error("HTTP error! status: ${response.status}"); } const data = await response.json(); return data; } catch (error) { console.error('Failed to load translations:', error); return {}; } } // Usage in a React component: import React, { useState, useEffect } from 'react'; function MyComponent({ locale }) { const [translations, setTranslations] = useState({}); useEffect(() => { loadTranslations(locale).then(data => setTranslations(data)); }, [locale]); return ( <div> {/* Use translations here */} </div> ); } """ This example fetches the translation file for the specified locale. It also include error handling and returns empty object on errors, preventing the app from crashing. Caching can be implemented by checking if translations for a locale already exists before fetching. ### 4.2 Caching Translations **Standard**: Cache fetched translations in memory to avoid redundant network requests. **Why**: Improves performance and reduces server load. **Do This**: Use a simple JavaScript object or a more sophisticated caching library to store translations. **Don't Do This**: Fetch the same translation file multiple times. **Example (Caching with a Simple Object):** """javascript const translationCache = {}; async function loadTranslations(locale) { if (translationCache[locale]) { return translationCache[locale]; // Return from cache; } try { const response = await fetch("/locales/${locale}.json"); if (!response.ok) { throw new Error("HTTP error! status: ${response.status}"); } const data = await response.json(); translationCache[locale] = data; // Store in cache return data; } catch (error) { console.error('Failed to load translations:', error); return {}; } } """ This example checks the "translationCache" before making a network request. If the translations are already cached, they are returned immediately, avoiding the network round trip. ## 5. Handling Dynamic Content ### 5.1 Placeholders and Variables **Standard**: Use placeholders or variables in translation strings to handle dynamic content. **Why**: Allows you to insert data into translated strings without hardcoding it. **Do This**: * Use a consistent placeholder syntax (e.g., "{{variable}}", "{variable}", "%s"). * Provide a mechanism for replacing placeholders with actual values. * Use libraries supporting pluralization and gender-specific text. **Don't Do This**: * Concatenate strings directly with translation keys. * Use different placeholder syntaxes inconsistently. **Example (Using Placeholders):** """javascript const translations = { 'en-US': { 'greeting': 'Hello, {{name}}!', 'itemCount': 'You have {{count}} items in your cart.', }, 'fr-CA': { 'greeting': 'Bonjour, {{name}}!', 'itemCount': 'Vous avez {{count}} articles dans votre panier.', }, }; function translate(key, locale, variables = {}) { let translatedText = translations[locale][key] || key; for (const variable in variables) { translatedText = translatedText.replace("{{${variable}}}", variables[variable]); } return translatedText; } // Usage: console.log(translate('greeting', 'en-US', { name: 'John' })); // Output: Hello, John! console.log(translate('itemCount', 'fr-CA', { count: 3 })); // Output: Vous avez 3 articles dans votre panier. """ This example defines placeholders using "{{variable}}" syntax. The "translate" function replaces these placeholders with the corresponding values from the "variables" object. Libraries like "i18next" or "Fluent" are more robust choices due to their wider and tested support for complex pluralization rules, gender forms, and number/date formatting. ### 5.2 Pluralization **Standard**: Handle pluralization correctly for different languages. **Why**: Pluralization rules vary significantly between languages. **Do This**: * Use a library that supports pluralization (e.g., "i18next", "Fluent"). * Provide different translation strings for different plural forms. **Don't Do This**: * Assume that all languages have the same pluralization rules as English. Hardcode singular/plural logic. **Example (Using i18next for Pluralization):** """javascript // i18next configuration (i18n.js) import i18n from 'i18next'; import { initReactI18next } from 'react-i18next'; i18n .use(initReactI18next) .init({ resources: { en: { translation: { 'itemCount_one': 'You have one item in your cart.', 'itemCount_other': 'You have {{count}} items in your cart.', }, }, fr: { translation: { 'itemCount_one': 'Vous avez un article dans votre panier.', 'itemCount_other': 'Vous avez {{count}} articles dans votre panier.', }, }, }, lng: 'en', fallbackLng: 'en', interpolation: { escapeValue: false, }, }); export default i18n; // React component import React from 'react'; import { useTranslation } from 'react-i18next'; function CartSummary({ count }) { const { t } = useTranslation(); return ( <p>{t('itemCount', { count })}</p> ); } // Usage: <CartSummary count={1} /> // Output: You have one item in your cart. <CartSummary count={3} /> // Output: You have 3 items in your cart. """ In this example, "i18next" is used to handle pluralization. Translation keys are defined with "_one" and "_other" suffixes to specify different plural forms. The "t" function automatically selects the correct form based on the "count" value. "Numeral.js" is often used alongside i18next to format the counts. ## 6. Performance Considerations ### 6.1 Minimizing Lookups **Standard**: Minimize the number of translation lookups performed during rendering. **Why**: Reduces the overhead of looking up translations for each component. **Do This**: Cache translated strings in components or use memoization techniques. **Don't Do This**: Perform translation lookups in render methods repeatedly without caching. **Example (Caching Translated Strings):** """jsx import React, { useState, useEffect } from 'react'; import { useTranslation } from 'react-i18next'; function MyComponent() { const { t } = useTranslation(); const [greeting, setGreeting] = useState(''); useEffect(() => { // Cache the translated string setGreeting(t('greeting', { name: 'John' })); }, [t]); return ( <div> <p>{greeting}</p> </div> ); } """ This example caches the translated "greeting" string in a state variable. The translation lookup is performed only once when the component mounts. The "useTranslation" hook's "t" function is included in the dependency array for the "useEffect" hook to account for changes to the translation function itself which happens on language changes. ### 6.2 Optimizing Translation Loading **Standard**: Optimize the loading of translation files to reduce initial load time. **Why**: A large translation file can significantly impact the application's startup performance. **Do This**: * Use code splitting to load translation files on demand. * Compress translation files to reduce their size. * Use a CDN to deliver translation files from a location close to the user. **Don't Do This**: * Load all translation files at application startup. * Serve uncompressed translation files. ## 7. Security Considerations ### 7.1 Preventing XSS Attacks **Standard**: Prevent cross-site scripting (XSS) attacks when displaying translated content. **Why**: Malicious translation strings can inject JavaScript code into the application. **Do This**: * Sanitize user-provided content before including it in translation strings. * Use a templating engine that automatically escapes HTML entities. **Don't Do This**: * Directly insert user-provided content into translation strings without sanitization. * Disable HTML escaping in the templating engine. **Example (Sanitizing User Input):** """javascript function sanitize(text) { const map = { '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }; return text.replace(/[&<>"']/g, function(m) { return map[m]; }); } const translations = { 'en-US': { 'comment': 'User {{username}} said: {{comment}}', }, }; function translate(key, locale, variables = {}) { let translatedText = translations[locale][key] || key; for (const variable in variables) { translatedText = translatedText.replace("{{${variable}}}", sanitize(variables[variable])); } return translatedText; } // Usage: const userInput = '<script>alert("XSS");</script>'; console.log(translate('comment', 'en-US', { username: 'John', comment: userInput })); // Output: User John said: <script>alert("XSS");</script> """ This example uses a "sanitize" function to escape HTML entities in user-provided content before inserting it into the translation string. This prevents the execution of malicious JavaScript code. ### 7.2 Secure Translation Storage **Standard**: Securely store and manage translation files. **Why**: Unauthorized modification of translation files can compromise the integrity of the application. **Do This**: * Store translation files in a secure location with restricted access. * Use version control to track changes to translation files. * Implement a review process for translation changes. **Don't Do This**: * Store translation files in a publicly accessible location. * Allow unauthorized users to modify translation files. ## 8. Conclusion Adhering to these coding standards for i18n state management ensures that your applications are maintainable, scalable, performant, and secure. By managing state effectively, developers can deliver a consistent and localized user experience across different languages and cultures. As tooling evolves, these guidelines can be adapted as long as the core principles remain the same.