@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/data/docs/routes/components-utilities-nimbus-i18n-provider.json

@@ -0,0 +1,295 @@
+{
+  "meta": {
+    "id": "Components-NimbusI18nProvider",
+    "title": "Nimbus i18n provider",
+    "exportName": "NimbusI18nProvider",
+    "description": "The NimbusI18nProvider component provides internationalization (i18n) context for React Aria components in your Nimbus application. It controls how dates, numbers, and other locale-specific content is formatted across all React Aria-based components.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/nimbus-i18n-provider/nimbus-i18n-provider.mdx",
+    "menu": [
+      "Components",
+      "Utilities",
+      "Nimbus i18n provider"
+    ],
+    "route": "components/utilities/nimbus-i18n-provider",
+    "tags": [
+      "component",
+      "i18n",
+      "internationalization",
+      "provider",
+      "react-aria"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Key features",
+        "href": "#key-features",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Basic usage",
+        "href": "#basic-usage",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Different locales",
+        "href": "#different-locales",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Multiple providers",
+        "href": "#multiple-providers",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nNimbusI18nProvider is a proxy component that wraps React Aria's I18nProvider,\nmaking it easy to set the locale for all React Aria components like DatePicker,\nCalendar, and NumberInput. This ensures consistent formatting across your\napplication.\n\n### Key features\n\n- **Locale-aware formatting**: Controls date, number, and currency formatting\n  based on locale\n- **React Aria integration**: Built specifically for React Aria components\n- **BCP47 locale codes**: Supports standard language-region codes (e.g.,\n  'en-US', 'de-DE')\n- **Type-safe**: Full TypeScript support\n- **Automatic propagation**: Locale settings cascade to all child React Aria\n  components\n\n### Resources\n\n[React Aria I18nProvider Docs](https://react-spectrum.adobe.com/react-aria/I18nProvider.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Basic usage\n\nWrap your application with NimbusI18nProvider to set the locale for React Aria\ncomponents:\n\n```jsx live\nconst App = () => (\n  <NimbusI18nProvider locale=\"en-US\">\n    <Stack direction=\"column\" gap=\"400\">\n      <Text>This app uses US English formatting</Text>\n      <DatePicker label=\"Select Date\" />\n    </Stack>\n  </NimbusI18nProvider>\n);\n```\n\n### Different locales\n\nChange the locale prop to switch formatting:\n\n```jsx live\nconst App = () => {\n  const [locale, setLocale] = React.useState(\"en-US\");\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"200\" wrap=\"wrap\">\n        <Button onClick={() => setLocale(\"en-US\")} size=\"sm\">\n          English (US)\n        </Button>\n        <Button onClick={() => setLocale(\"en-GB\")} size=\"sm\">\n          English (UK)\n        </Button>\n        <Button onClick={() => setLocale(\"de-DE\")} size=\"sm\">\n          Deutsch\n        </Button>\n        <Button onClick={() => setLocale(\"es-ES\")} size=\"sm\">\n          Español\n        </Button>\n        <Button onClick={() => setLocale(\"fr-FR\")} size=\"sm\">\n          Français\n        </Button>\n        <Button onClick={() => setLocale(\"ja-JP\")} size=\"sm\">\n          日本語\n        </Button>\n      </Stack>\n\n      <NimbusI18nProvider locale={locale}>\n        <Stack direction=\"column\" gap=\"400\">\n          <Text fontWeight=\"600\">Current Locale: {locale}</Text>\n          <DatePicker label=\"Select Date\" />\n          <NumberInput\n            label=\"Amount\"\n            defaultValue={1234.56}\n            minValue={0}\n            formatOptions={{\n              style: \"currency\",\n              currency: locale.startsWith(\"ja\") ? \"JPY\" : locale.startsWith(\"en-GB\") ? \"GBP\" : \"USD\"\n            }}\n          />\n        </Stack>\n      </NimbusI18nProvider>\n    </Stack>\n  );\n};\n```\n\n### Multiple providers\n\nYou can nest NimbusI18nProviders to use different locales in different parts of\nyour app:\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <NimbusI18nProvider locale=\"en-US\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">US Section</Text>\n        <DatePicker label=\"Date\" />\n      </Stack>\n    </NimbusI18nProvider>\n\n    <NimbusI18nProvider locale=\"de-DE\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">German Section</Text>\n        <DatePicker label=\"Datum\" />\n      </Stack>\n    </NimbusI18nProvider>\n\n    <NimbusI18nProvider locale=\"ja-JP\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">Japanese Section</Text>\n        <DatePicker label=\"日付\" />\n      </Stack>\n    </NimbusI18nProvider>\n  </Stack>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nNimbusI18nProvider is a proxy component that wraps React Aria's I18nProvider,\nmaking it easy to set the locale for all React Aria components like DatePicker,\nCalendar, and NumberInput. This ensures consistent formatting across your\napplication.\n\n### Key features\n\n- **Locale-aware formatting**: Controls date, number, and currency formatting\n  based on locale\n- **React Aria integration**: Built specifically for React Aria components\n- **BCP47 locale codes**: Supports standard language-region codes (e.g.,\n  'en-US', 'de-DE')\n- **Type-safe**: Full TypeScript support\n- **Automatic propagation**: Locale settings cascade to all child React Aria\n  components\n\n### Resources\n\n[React Aria I18nProvider Docs](https://react-spectrum.adobe.com/react-aria/I18nProvider.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Basic usage\n\nWrap your application with NimbusI18nProvider to set the locale for React Aria\ncomponents:\n\n```jsx live\nconst App = () => (\n  <NimbusI18nProvider locale=\"en-US\">\n    <Stack direction=\"column\" gap=\"400\">\n      <Text>This app uses US English formatting</Text>\n      <DatePicker label=\"Select Date\" />\n    </Stack>\n  </NimbusI18nProvider>\n);\n```\n\n### Different locales\n\nChange the locale prop to switch formatting:\n\n```jsx live\nconst App = () => {\n  const [locale, setLocale] = React.useState(\"en-US\");\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"200\" wrap=\"wrap\">\n        <Button onClick={() => setLocale(\"en-US\")} size=\"sm\">\n          English (US)\n        </Button>\n        <Button onClick={() => setLocale(\"en-GB\")} size=\"sm\">\n          English (UK)\n        </Button>\n        <Button onClick={() => setLocale(\"de-DE\")} size=\"sm\">\n          Deutsch\n        </Button>\n        <Button onClick={() => setLocale(\"es-ES\")} size=\"sm\">\n          Español\n        </Button>\n        <Button onClick={() => setLocale(\"fr-FR\")} size=\"sm\">\n          Français\n        </Button>\n        <Button onClick={() => setLocale(\"ja-JP\")} size=\"sm\">\n          日本語\n        </Button>\n      </Stack>\n\n      <NimbusI18nProvider locale={locale}>\n        <Stack direction=\"column\" gap=\"400\">\n          <Text fontWeight=\"600\">Current Locale: {locale}</Text>\n          <DatePicker label=\"Select Date\" />\n          <NumberInput\n            label=\"Amount\"\n            defaultValue={1234.56}\n            minValue={0}\n            formatOptions={{\n              style: \"currency\",\n              currency: locale.startsWith(\"ja\") ? \"JPY\" : locale.startsWith(\"en-GB\") ? \"GBP\" : \"USD\"\n            }}\n          />\n        </Stack>\n      </NimbusI18nProvider>\n    </Stack>\n  );\n};\n```\n\n### Multiple providers\n\nYou can nest NimbusI18nProviders to use different locales in different parts of\nyour app:\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <NimbusI18nProvider locale=\"en-US\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">US Section</Text>\n        <DatePicker label=\"Date\" />\n      </Stack>\n    </NimbusI18nProvider>\n\n    <NimbusI18nProvider locale=\"de-DE\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">German Section</Text>\n        <DatePicker label=\"Datum\" />\n      </Stack>\n    </NimbusI18nProvider>\n\n    <NimbusI18nProvider locale=\"ja-JP\">\n      <Stack direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">Japanese Section</Text>\n        <DatePicker label=\"日付\" />\n      </Stack>\n    </NimbusI18nProvider>\n  </Stack>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Key features",
+          "href": "#key-features",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Different locales",
+          "href": "#different-locales",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multiple providers",
+          "href": "#multiple-providers",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <NimbusI18nProvider locale=\"en-US\">\n    <Text>Content with proper locale formatting</Text>\n  </NimbusI18nProvider>\n);\n```\n\n### Accessibility standards\n\n- **Provide valid locale codes:** Always provide a valid BCP47 language tag\n  (e.g., `en-US`, `de-DE`, `fr-FR`) to ensure proper formatting and\n  pronunciation.\n- **Use region-specific codes:** Use region-specific codes when formatting\n  differs (e.g., date order, decimal separators, number formatting).\n- **Locale-appropriate formatting:** Dates, numbers, and currency are announced\n  in locale-appropriate formats by screen readers.\n- **Proper pronunciation:** Screen readers use the specified locale for correct\n  pronunciation of content.\n- **ARIA labels reflect locale conventions:** Ensures ARIA labels and\n  announcements follow locale conventions.\n- **Test with screen readers:** Always test with actual screen readers to verify\n  proper pronunciation and formatting.\n\n## Resources\n\n- [BCP47 Language Tags](https://www.w3.org/International/articles/language-tags/)\n- [WCAG 3.1.2 Language of Parts](https://www.w3.org/WAI/WCAG21/Understanding/language-of-parts.html)\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n\n## API reference\n\n<PropsTable id=\"NimbusI18nProvider\" />",
+      "toc": [
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nUse NimbusI18nProvider strategically to support international date and number\nformatting.\n\n### Best practices\n\n- **Wrap at root level**: Place NimbusI18nProvider at the root of your\n  application to provide i18n context to all React Aria components\n- **Use BCP47 codes**: Always use proper BCP47 language tags (e.g., 'en-US',\n  'de-DE', 'fr-FR')\n- **Regional specificity**: Include region codes when formatting differs by\n  region (e.g., 'en-US' vs 'en-GB')\n- **Dynamic locale**: Allow users to switch locales at runtime for better user\n  experience\n- **Consistent currency**: When formatting currency, ensure the currency code\n  matches the locale expectations\n\n### When to use\n\n> [!TIP]\\\n> When to use\n\n- **International applications**: When your app serves users in multiple\n  countries\n- **Date formatting**: When you need locale-appropriate date formats (MM/DD/YYYY\n  vs DD.MM.YYYY)\n- **Number formatting**: When you need locale-appropriate number separators\n  (1,234.56 vs 1.234,56)\n- **Currency formatting**: When displaying prices in different currencies and\n  formats\n- **React Aria components**: When using DatePicker, Calendar, NumberInput, or\n  other React Aria date/number components\n\n> [!CAUTION]\\\n> When not to use\n\n- **Single locale apps**: If your app only targets one locale, you may not need\n  NimbusI18nProvider\n- **Text translation**: This component provides locale context for React Aria\n  components. Nimbus components use compiled message dictionaries (see\n  [i18n guidelines](../../../../docs/file-type-guidelines/i18n.md) for details)\n- **Non-React Aria components**: This only affects React Aria components, not\n  general HTML or other component libraries\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}