# API Integration Standards for Internationalization
This document outlines coding standards for integrating APIs into applications with a focus on internationalization (i18n). It provides guidance for developers on how to build maintainable, performant, and secure i18n-aware API integrations.
## 1. Architectural Considerations
### 1.1. API Design for I18n
When designing or consuming APIs, ensure that the API is designed with internationalization in mind. This impacts both the request and response structure.
**Do This:**
* Design APIs to accept "Accept-Language" headers in requests.
* Design APIs to return localized content based on the "Accept-Language" header.
* Utilize standard HTTP headers like "Content-Language" to indicate the language of the response body.
* Use ISO language codes (e.g., "en", "fr", "de") and region codes (e.g., "US", "CA", "DE") for language tags.
**Don't Do This:**
* Assume that the user's language is the same as the application's default language.
* Hardcode language codes in the API calls or backend logic.
* Ignore the "Accept-Language" header.
**Why:** Proper API design ensures consistency across different parts of the application and simplifies the localization process.
**Example (API Request):**
"""http
GET /products/123 HTTP/1.1
Host: api.example.com
Accept-Language: fr-CA, fr;q=0.8, en-US;q=0.5, en;q=0.3
"""
**Example (API Response):**
"""http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: fr-CA
{
"id": 123,
"name": "Produit",
"description": "Un excellent produit."
}
"""
### 1.2. Content Negotiation
APIs should support content negotiation, allowing clients to request resources in different languages or formats.
**Do This:**
* Implement content negotiation using "Accept-Language" and "Content-Language" HTTP headers.
* Provide a default language for cases where the requested language is not supported.
* Use quality values (q-values) in the "Accept-Language" header to prioritize languages.
**Don't Do This:**
* Force the client to explicitly request the localized version through query parameters or custom headers (unless absolutely necessary).
* Ignore the client's preferred languages specified in the "Accept-Language" header.
**Why:** Content negotiation provides a flexible mechanism for serving localized content, enhancing the user experience.
**Example:**
The client sends: "Accept-Language: de-DE, de;q=0.9, en;q=0.8"
The server responds with German content ("de-DE") if available, German content ("de") if "de-DE" is unavailable, or English content ("en") if neither German variant is available. The server should set "Content-Language" accordingly.
### 1.3. Versioning
When making changes to the API that affect I18n (e.g., adding support for new languages), use API versioning to avoid breaking existing clients.
**Do This:**
* Use semantic versioning for your API.
* Include the API version number in the URL or in a custom header.
* Provide a migration path for clients to upgrade to newer API versions.
* Clearly document I18n-related changes in the API version release notes.
**Don't Do This:**
* Introduce breaking changes without versioning.
* Make assumptions about the client's ability to handle new language tags or formats without proper communication.
**Why:** Versioning isolates changes to the localization strategy, preventing unexpected behavior in older application versions.
**Example:**
* "api.example.com/v1/products" (Initial version with English only)
* "api.example.com/v2/products" (Supports content negotiation for multiple languages)
### 1.4 Error Handling
API error responses should also be internationalized, providing error messages in the user’s preferred language.
**Do This:**
* Translate error messages.
* Include the error code and a user-friendly message ID.
* Use the "Accept-Language" header to return localized error messages.
* Provide default error messages in a fallback language.
**Don't Do This:**
* Return error messages in the default server language only.
* Expose sensitive information in error messages, even in a localized format.
* Use untranslated error messages as a shortcut.
**Why:** Localized error messages improve the user experience and help users understand and resolve issues more quickly.
## 2. Implementation Standards
### 2.1. Locale Handling
Ensure the application correctly handles locales when interacting with APIs.
**Do This:**
* Extract the locale from the "Accept-Language" header or user preferences.
* Validate the locale against a list of supported locales.
* Use consistent naming conventions for locale identifiers (e.g., "en-US", "fr-CA").
* Normalize locale identifiers obtained from different sources (e.g., browser settings, API responses).
**Don't Do This:**
* Rely solely on the browser's default locale.
* Use hardcoded locale identifiers.
* Ignore potential security issues arising from arbitrary user-provided locales.
**Why:** Consistent and accurate locale handling ensures that the correct localized content is requested from and presented to the user.
**Example (JavaScript):**
"""javascript
function getLocaleFromHeader(header) {
const locales = header.split(',').map(locale => {
const [lang, quality] = locale.split(';q=');
return {
lang: lang.trim(),
quality: quality ? parseFloat(quality) : 1
};
}).sort((a, b) => b.quality - a.quality);
return locales.length > 0 ? locales[0].lang : 'en-US'; // Default locale
}
const acceptLanguageHeader = req.headers['accept-language'];
const userLocale = getLocaleFromHeader(acceptLanguageHeader);
if (!['en-US', 'fr-CA', 'de-DE'].includes(userLocale)) {
userLocale = 'en-US'; // Fallback
}
"""
### 2.2. Formatting and Parsing
When passing data to APIs or displaying data received from APIs, format and parse data according to the user's locale.
**Do This:**
* Use locale-aware formatting for dates, numbers, and currencies.
* Use appropriate date and time formats for the user's locale (e.g., "MM/DD/YYYY" vs. "DD/MM/YYYY").
* Use the correct decimal and thousand separators for numbers.
* Convert currencies to the user's local currency using an external API if necessary (with appropriate disclaimers about exchange rates).
**Don't Do This:**
* Use the application's default formatting for all locales.
* Assume that all users understand the same date, number, and currency formats.
**Why:** Correct formatting improves the user experience and ensures that data is displayed in a way that is familiar and understandable to the user.
**Example (JavaScript using "Intl" API):**
"""javascript
const price = 1234.56;
const locale = 'de-DE';
const formattedPrice = new Intl.NumberFormat(locale, {
style: 'currency',
currency: 'EUR'
}).format(price);
console.log(formattedPrice); // Output: 1.234,56 €
const date = new Date();
const formattedDate = new Intl.DateTimeFormat(locale, {
year: 'numeric',
month: 'long',
day: 'numeric'
}).format(date);
console.log(formattedDate); // Output: 11. Juli 2024
"""
### 2.3. Character Encoding
Ensure that character encoding is handled correctly to support different languages and character sets.
**Do This:**
* Use UTF-8 encoding for all data transmitted to and received from APIs.
* Set the "Content-Type" header with the correct character encoding (e.g., "application/json; charset=utf-8").
* Handle Unicode characters correctly in the application code.
**Don't Do This:**
* Use legacy character encodings like ISO-8859-1.
* Assume that all characters are ASCII characters.
* Ignore potential security vulnerabilities related to character encoding issues (e.g., cross-site scripting).
**Why:** UTF-8 is the standard character encoding for the web and supports a wide range of characters from different languages, preventing data corruption and display issues.
### 2.4. String Externalization
Externalize all strings that need to be localized. Don't hardcode strings directly in the code.
**Do This:**
* Store localized strings in resource files.
* Use keys or IDs to identify strings in the code.
* Use a localization library or framework to manage translations.
* Load localized strings based on the user's locale.
**Don't Do This:**
* Hardcode strings directly in components or API calls.
* Use string concatenation to build localized strings.
* Use a single resource file for all languages (separate files per locale are easier to manage).
**Why:** String externalization makes it easier to translate the application into different languages and maintain translations over time.
**Example (using a resource file):**
Resource file ("en-US.json"):
"""json
{
"greeting": "Hello, {name}!",
"product.description": "This is a great product."
}
"""
Resource file ("fr-CA.json"):
"""json
{
"greeting": "Bonjour, {name}!",
"product.description": "Ceci est un excellent produit."
}
"""
Code (JavaScript using "i18next"):
"""javascript
import i18next from 'i18next';
i18next.init({
lng: 'en-US', // Default language
resources: {
'en-US': {
translation: require('./locales/en-US.json')
},
'fr-CA': {
translation: require('./locales/fr-CA.json')
}
}
});
function greet(name) {
return i18next.t('greeting', { name: name });
}
console.log(greet('John')); // Output: Hello, John!
i18next.changeLanguage('fr-CA');
console.log(greet('Jean')); // Output: Bonjour, Jean!
"""
### 2.5. Placeholder Handling
When externalizing strings, handle placeholders correctly.
**Do This:**
* Use consistent placeholder syntax (e.g., "{name}", "{{name}}").
* Ensure placeholders are properly escaped to avoid injection vulnerabilities.
* Use a localization library or framework that supports placeholder replacement.
**Don't Do This:**
* Use string concatenation to replace placeholders.
* Allow users to inject arbitrary code through placeholders.
* Ignore potential formatting issues when replacing placeholders with localized values.
**Why:** Proper placeholder handling ensures that localized strings are displayed correctly and prevents security vulnerabilities.
### 2.6. Pluralization
Handle pluralization correctly for different languages.
**Do This:**
* Use a localization library or framework that supports pluralization rules for different languages. "i18next" has excellent pluralization support.
* Provide different translations for singular and plural forms.
* Consider languages with more than two plural forms (e.g., Arabic, Russian).
**Don't Do This:**
* Use simple if/else statements to handle pluralization.
* Assume that all languages have the same pluralization rules.
**Why:** Correct pluralization ensures that messages are grammatically correct in different languages.
**Example (using "i18next"):**
Resource file ("en-US.json"):
"""json
{
"itemCount_0": "No items",
"itemCount_1": "One item",
"itemCount_plural": "{count} items"
}
"""
Code (JavaScript):
"""javascript
import i18next from 'i18next';
i18next.init({
lng: 'en-US', // Default language
resources: {
'en-US': {
translation: require('./locales/en-US.json')
}
}
});
function displayItemCount(count) {
return i18next.t('itemCount', { count: count });
}
console.log(displayItemCount(0)); // Output: No items
console.log(displayItemCount(1)); // Output: One item
console.log(displayItemCount(5)); // Output: 5 items
"""
### 2.7. API Authentication
API authentication mechanisms should be I18n-agnostic. Locale information should not be part of the authentication process.
**Do This:**
* Use standard authentication mechanisms, such as OAuth 2.0 or JWT.
* Store user locale preferences separately from authentication credentials.
* Ensure that authentication tokens don't contain any locale-specific information.
**Don't Do This:**
* Include locale information in the authentication process.
* Use different authentication schemas for different locales.
**Why:** Separating authentication from localization simplifies the authentication process and improves security.
## 3. Security Considerations
### 3.1. Input Validation
Sanitize and validate all data received from APIs to prevent potential security vulnerabilities, such as cross-site scripting (XSS) or SQL injection.
**Do This:**
* Use appropriate escaping techniques for HTML, JavaScript, and SQL.
* Validate the data type and format of all input fields.
* Limit the length of input fields to prevent buffer overflows.
* Implement input validation on both the client-side and server-side.
**Don't Do This:**
* Trust data received from APIs without validation.
* Use insecure string concatenation to build SQL queries or HTML.
**Why:** Input validation is crucial for preventing security vulnerabilities and protecting the application from malicious attacks.
### 3.2. Output Encoding
Encode all data displayed in the user interface to prevent XSS attacks.
**Do This:**
* Use HTML encoding for data displayed in HTML.
* Use JavaScript encoding for data used in JavaScript code.
* Use URL encoding for data used in URLs.
* Use a templating engine that automatically encodes output data.
**Don't Do This:**
* Display data directly without encoding.
* Disable output encoding in the templating engine in the name of simplicity.
**Why:** Output encoding prevents malicious users from injecting JavaScript code into the application and stealing user data.
### 3.3. Locale Injection
Avoid allowing users to directly specify the locale in a way that could be exploited to inject malicious code.
**Do This:**
* Validate user-provided locales against a known list of supported locales.
* Use a secure method for storing user locale preferences (e.g., in a database or server-side session).
* Implement proper error handling to gracefully handle invalid locales.
* Consider using a library specifically designed to handle locale-related security issues.
**Don't Do This:**
* Trust user-provided locales without validation.
* Store user locale preferences in a way that could be easily manipulated by the user (e.g., in a client-side cookie).
**Why:** Locale injection vulnerabilities can allow attackers to execute arbitrary code on the server or client, compromising the application's security.
## 4. Performance Optimization
### 4.1. Caching
Cache localized API responses to improve performance and reduce server load.
**Do This:**
* Use a caching mechanism, such as Redis or Memcached.
* Cache localized data based on the user's locale.
* Set appropriate cache expiration times.
* Use HTTP caching headers (e.g., "Cache-Control", "Expires") to enable client-side caching.
**Don't Do This:**
* Cache data without considering the user's locale.
* Cache sensitive data without proper security measures.
* Set excessively long cache expiration times.
**Why:** Caching reduces the number of API calls and improves the application's responsiveness, especially for frequently accessed localized data.
### 4.2. Compression
Use compression to reduce the size of API responses.
**Do This:**
* Enable gzip compression on the server-side.
* Use HTTP compression headers (e.g., "Content-Encoding: gzip").
* Ensure that the client supports compression (most modern browsers do).
**Don't Do This:**
* Disable compression for localized API responses.
* Use compression algorithms that are not widely supported.
**Why:** Compression reduces the amount of data transmitted over the network, improving performance and reducing bandwidth consumption.
### 4.3. Lazy Loading
Load localized data only when it is needed.
**Do This:**
* Use lazy loading techniques to load localized resources on demand
* Load non-visible translations asynchronously.
**Don't Do This:**
* Load all localized data at once.
* Load localized data that is not currently needed.
**Why:** Lazy loading improves the application's startup time and reduces memory consumption, especially for applications with a large number of supported locales.
## 5. Testing
### 5.1. Unit Tests
Write unit tests to verify that the application correctly handles locales and localized data.
**Do This:**
* Test different locales and languages.
* Test different date, number, and currency formats.
* Test pluralization rules for different languages.
* Test error handling for invalid locales.
**Don't Do This:**
* Test only the default locale.
* Ignore potential localization issues in unit tests.
**Why:** Unit tests help to identify and fix localization issues early in the development process.
### 5.2. Integration Tests
Write integration tests to verify that the application correctly interacts with localized APIs.
**Do This:**
* Test API calls with different "Accept-Language" headers.
* Test API responses with localized data.
* Test the end-to-end flow of localized data from the API to the user interface.
**Don't Do This:**
* Test only a single API endpoint.
* Ignore potential localization issues integration tests.
**Why:** Integration tests ensure that the application correctly handles localized data across different components and systems.
### 5.3. End-to-End Tests
Perform end-to-end tests to verify that the application is fully localized and that all localized data is displayed correctly to the user.
**Do This:**
* Test the application with different user locales.
* Test the application with different input methods and character sets.
* Test the application with assistive technologies, such as screen readers.
**Don't Do This:**
* Skip end-to-end testing for localized applications.
* Assume that localization is correct without thorough testing.
**Why:** End-to-end tests ensure that the application is fully localized and accessible to users from different regions and cultures.
By following these coding standards, developers can build high-quality, maintainable, and secure i18n-aware API integrations. This ensures a better user experience and reduces the risk of potential localization issues.
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.