Enhancing Angular Applications with Internationalization and Localization

{
  "title": "Enhancing Angular Applications with Internationalization and Localization",
  "description": "Techniques for implementing internationalization and localization to support multiple languages and regions in Angular projects.",
  "category": "Angular Cursor Rules",
  "rules": [
    {
      "id": "angular-i18n-001",
      "description": "Plan for internationalization from the project's inception to avoid retrofitting challenges.",
      "severity": "warning",
      "recommendation": "Incorporate Angular's i18n capabilities early by marking text for translation using the `i18n` attribute in templates.",
      "example": {
        "before": "<h1>Welcome to our website!</h1>",
        "after": "<h1 i18n>Welcome to our website!</h1>"
      }
    },
    {
      "id": "angular-i18n-002",
      "description": "Avoid hardcoding locale-sensitive data such as dates, times, and currencies.",
      "severity": "error",
      "recommendation": "Utilize Angular's built-in pipes like `DatePipe` and `CurrencyPipe` to format data according to the user's locale.",
      "example": {
        "before": "<p>Today's date is: 2025-06-03</p>",
        "after": "<p>Today's date is: {{ today | date:'longDate' }}</p>"
      }
    },
    {
      "id": "angular-i18n-003",
      "description": "Provide context for translators to ensure accurate translations.",
      "severity": "warning",
      "recommendation": "Use the `i18n` attribute with descriptions and custom IDs to give translators necessary context.",
      "example": {
        "before": "<button>Ship</button>",
        "after": "<button i18n=\"@@shipButton|Button label for shipping products\">Ship</button>"
      }
    },
    {
      "id": "angular-i18n-004",
      "description": "Use interpolation for dynamic content to maintain flexibility in translations.",
      "severity": "warning",
      "recommendation": "Implement Angular's interpolation syntax (`{{ }}`) instead of string concatenation for dynamic content.",
      "example": {
        "before": "<p>{{ userName }} has {{ itemCount }} items in their cart.</p>",
        "after": "<p i18n=\"@@cartStatus\">{{ userName }} has {{ itemCount }} items in their cart.</p>"
      }
    },
    {
      "id": "angular-i18n-005",
      "description": "Handle pluralization and gender-specific translations appropriately.",
      "severity": "error",
      "recommendation": "Utilize Angular's ICU message format to manage complex linguistic rules.",
      "example": {
        "before": "<p>{{ itemCount }} items found.</p>",
        "after": "<p i18n=\"@@itemsFound\">{itemCount, plural, =0 {No items found.} =1 {One item found.} other {# items found.}}</p>"
      }
    },
    {
      "id": "angular-i18n-006",
      "description": "Ensure support for right-to-left (RTL) languages.",
      "severity": "error",
      "recommendation": "Implement RTL support by adjusting layouts and styles to accommodate languages like Arabic and Hebrew.",
      "example": {
        "before": "/* No RTL support */",
        "after": "[dir='rtl'] .example-class { transform: scaleX(-1); }"
      }
    },
    {
      "id": "angular-i18n-007",
      "description": "Avoid hardcoding text within TypeScript files.",
      "severity": "warning",
      "recommendation": "Use Angular's `$localize` function to mark strings for translation in TypeScript code.",
      "example": {
        "before": "const message = 'Welcome to our application!';",
        "after": "const message = $localize`:@@welcomeMessage:Welcome to our application!`;"
      }
    },
    {
      "id": "angular-i18n-008",
      "description": "Manage translation files efficiently to support multiple languages.",
      "severity": "warning",
      "recommendation": "Organize translation files systematically and consider using libraries like `@ngx-translate/core` for dynamic language loading.",
      "example": {
        "before": "/* Unorganized translation files */",
        "after": "assets/i18n/en.json, assets/i18n/es.json, assets/i18n/fr.json"
      }
    },
    {
      "id": "angular-i18n-009",
      "description": "Test the application comprehensively across all supported languages.",
      "severity": "error",
      "recommendation": "Perform localization testing to identify and fix issues related to layout, functionality, and translation accuracy.",
      "example": {
        "before": "/* No localization testing */",
        "after": "/* Conducted localization testing for en, es, fr locales */"
      }
    },
    {
      "id": "angular-i18n-010",
      "description": "Consider cultural differences in design and content.",
      "severity": "warning",
      "recommendation": "Adapt UI/UX elements, images, and content to align with cultural norms and preferences of target locales.",
      "example": {
        "before": "/* Generic images */",
        "after": "/* Culturally relevant images for each locale */"
      }
    }
  ]
}