Skip to content

Commit

Permalink
A few doc changes
Browse files Browse the repository at this point in the history
  • Loading branch information
dBianchii committed Sep 23, 2024
1 parent 88718fa commit 95a2f40
Show file tree
Hide file tree
Showing 3 changed files with 11 additions and 9 deletions.
4 changes: 2 additions & 2 deletions docs/pages/docs/design-principles.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <PartnerContentLink href="https://crowdin.com/">Crowdin</PartnerContentLink>.

`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)).

Expand All @@ -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 <PartnerContentLink href="https://crowdin.com/">Crowdin</PartnerContentLink> 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)**

Expand Down
8 changes: 5 additions & 3 deletions docs/pages/docs/usage/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <PartnerContentLink name="localization-management-intro" href="https://store.crowdin.com/github">Crowdin's GitHub integration</PartnerContentLink>, 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 <PartnerContentLink name="localization-management-intro" href="https://store.crowdin.com/github">Crowdin's GitHub integration</PartnerContentLink>, 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:

Expand Down Expand Up @@ -486,8 +486,6 @@ Note that `formats` are not automatically inherited by Client Components. If you
</Tab>
</Tabs>

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
Expand All @@ -502,6 +500,10 @@ function Component() {
}
```

<Callout>
To further improve your experience and ensure formatting consistency, you can [configure the typescript integration for global formats](/docs/workflows/typescript#formats).
</Callout>

Global formats for numbers, dates and times can be referenced in messages too:

```json filename="en.json"
Expand Down
8 changes: 4 additions & 4 deletions docs/pages/docs/workflows/typescript.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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"
{
Expand Down Expand Up @@ -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:

Expand Down

0 comments on commit 95a2f40

Please sign in to comment.