From 95a2f40a7d4c8f6d54ef39c95ad0a0f4ebd3776a Mon Sep 17 00:00:00 2001 From: Gabriel Bianchi Date: Mon, 23 Sep 2024 08:43:22 -0300 Subject: [PATCH] A few doc changes --- docs/pages/docs/design-principles.mdx | 4 ++-- docs/pages/docs/usage/configuration.mdx | 8 +++++--- docs/pages/docs/workflows/typescript.mdx | 8 ++++---- 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/pages/docs/design-principles.mdx b/docs/pages/docs/design-principles.mdx index 555d7f85a..af5ba8ab8 100644 --- a/docs/pages/docs/design-principles.mdx +++ b/docs/pages/docs/design-principles.mdx @@ -54,7 +54,7 @@ For text formatting, `next-intl` is based on [International Components for Unico By being based on standards, `next-intl` ensures that your internationalization code is future-proof and feels familiar to developers who have existing experience with internationalization. Additionally, relying on standards ensures that `next-intl` integrates well with translation management systems like Crowdin. -`next-intl` uses a [nested style](/docs/usage/messages#structuring-messages) to provide structure to messages, allowing to express hierarchies of messages without redundancy. By supporting only a single style, we can offer advanced features that rely on these assumptions like [type-safety for messages](/docs/workflows/typescript#strict-typing-of-messages). If you're coming from a different style, you can consider migrating to the nested style (see "Can I use a different style for structuring my messages?" in [the structuring messages docs](/docs/usage/messages#structuring-messages)). +`next-intl` uses a [nested style](/docs/usage/messages#structuring-messages) to provide structure to messages, allowing to express hierarchies of messages without redundancy. By supporting only a single style, we can offer advanced features that rely on these assumptions like [type-safety for messages](/docs/workflows/typescript#messages). If you're coming from a different style, you can consider migrating to the nested style (see "Can I use a different style for structuring my messages?" in [the structuring messages docs](/docs/usage/messages#structuring-messages)). As standards can change, `next-intl` is expected to keep up with the latest developments in the ECMAScript standard (e.g. [`Temporal`](https://tc39.es/proposal-temporal/docs/) and [`Intl.MessageFormat`](https://github.com/tc39/proposal-intl-messageformat)). @@ -70,7 +70,7 @@ Typical apps require some of the following integrations: These are typically used to manage translations and to [collaborate with translators](/docs/workflows/localization-management). Services like Crowdin provide a wide range of features, allowing translators to work in a web-based interface on translations, while providing different mechanisms to sync translations with your app. -`next-intl` integrates well with these services as it uses ICU message syntax for defining text labels, which is a widely supported standard. The recommended way to store messages is in JSON files that are structured by locale since this is a popular format that can be imported into a TMS. While it's recommended to have at least the messages for the default locale available locally (e.g. for [type-safe messages](/docs/workflows/typescript#strict-typing-of-messages)), you can also load messages dynamically, e.g. from a CDN that your TMS provides. +`next-intl` integrates well with these services as it uses ICU message syntax for defining text labels, which is a widely supported standard. The recommended way to store messages is in JSON files that are structured by locale since this is a popular format that can be imported into a TMS. While it's recommended to have at least the messages for the default locale available locally (e.g. for [type-safe messages](/docs/workflows/typescript#messages)), you can also load messages dynamically, e.g. from a CDN that your TMS provides. **Content Management Systems (CMS)** diff --git a/docs/pages/docs/usage/configuration.mdx b/docs/pages/docs/usage/configuration.mdx index 2a3b1d630..f8a891ee4 100644 --- a/docs/pages/docs/usage/configuration.mdx +++ b/docs/pages/docs/usage/configuration.mdx @@ -199,7 +199,7 @@ The most crucial aspect of internationalization is providing labels based on the ... ``` -Colocating your messages with app code is beneficial because it allows developers to make changes quickly and additionally, you can use the shape of your local messages for [type checking](/docs/workflows/typescript#strict-typing-of-messages). Translators can collaborate on messages by using CI tools, such as Crowdin's GitHub integration, which allows changes to be synchronized directly into your code repository. +Colocating your messages with app code is beneficial because it allows developers to make changes quickly and additionally, you can use the shape of your local messages for [type checking](/docs/workflows/typescript#messages). Translators can collaborate on messages by using CI tools, such as Crowdin's GitHub integration, which allows changes to be synchronized directly into your code repository. That being said, `next-intl` is agnostic to how you store messages and allows you to freely define an async function that fetches them while your app renders: @@ -486,8 +486,6 @@ Note that `formats` are not automatically inherited by Client Components. If you -To further improve your experience and ensure formatting consistency, you can [configure the typescript integration for global formats](/docs/workflows/typescript#strict-typing-of-global-formats). - Once you have `formats` set up, you can use them in your components via `useFormatter`: ```tsx @@ -502,6 +500,10 @@ function Component() { } ``` + + To further improve your experience and ensure formatting consistency, you can [configure the typescript integration for global formats](/docs/workflows/typescript#formats). + + Global formats for numbers, dates and times can be referenced in messages too: ```json filename="en.json" diff --git a/docs/pages/docs/workflows/typescript.mdx b/docs/pages/docs/workflows/typescript.mdx index 31cf9236b..bb441d01f 100644 --- a/docs/pages/docs/workflows/typescript.mdx +++ b/docs/pages/docs/workflows/typescript.mdx @@ -2,9 +2,9 @@ import Callout from 'components/Callout'; # TypeScript integration -## Strict typing of messages +`next-intl` integrates seamlessly with TypeScript right out of the box, requiring no additional setup. However, you can define the shape of your messages and global formats to enable autocompletion and type safety for your namespaces, message keys and formats. -`next-intl` integrates with TypeScript out-of-the box without additional setup. You can however provide the shape of your messages to get autocompletion and type safety for your namespaces and message keys. +## Messages ```json filename="messages.json" { @@ -50,9 +50,9 @@ You can freely define the interface, but if you have your messages available loc 4. Your type declaration file is included in `tsconfig.json`. 5. Your editor has loaded the most recent type declarations. When in doubt, you can restart. -## Strict typing of global formats +## Formats -`next-intl` provides a way to define [global formats](/docs/usage/configuration#formats) for your application. You can provide the type of your formats similarly to how you [define the type of messages](#strict-typing-of-messages). +`next-intl` provides a way to define [global formats](/docs/usage/configuration#formats) for your application. You can provide the type of your formats similarly to how you define the type of messages. First, define your formats and export them from a file: