Skip to content

Commit

Permalink
docs: rephrase docs and readme (#1912)
Browse files Browse the repository at this point in the history 
* Rephrase warning note

* fix(docs): rephrase basic usage

* Add spaces in vue code blocks

* typo: "documentation"

* fix readme typo

* update composable sentences + minor changes
  • Loading branch information
@kuroji-fusky
kuroji-fusky authored Mar 9, 2023
1 parent f3bacb5 commit 4aeeeec
Show file tree
Hide file tree
Showing 3 changed files with 31 additions and 37 deletions.
6 changes: 3 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ If you would like to use the stable version for Nuxt 2, please see the [`main` b

### Install with `next` tag

1. Add the following line to the `devDependencies` wiht package manager:
1. Add the following line to the `devDependencies` with your package manager:

```sh
# Using npm
Expand Down Expand Up @@ -55,7 +55,7 @@ pnpm install --shamefully-hoist -D @nuxtjs/i18n@next

2. Run `npm install` or `yarn` or `pnpm install --shamefully-hoist`.

3. Add `@nuxtjs/i18n` to the `modules` section of `nuxt.config.ts`
3. Add `@nuxtjs/i18n` to the `modules` section of `nuxt.config.ts`.

```ts
{
Expand All @@ -69,7 +69,7 @@ pnpm install --shamefully-hoist -D @nuxtjs/i18n@next

[Read more v8 documentation](https://v8.i18n.nuxtjs.org/).

Keep in mind that not all features are supported yet and some things might be broken.
Keep in mind that not all features are currently supported yet and some things might be broken.

## 🔗 Links
- 📘 [Documentation for v8](https://v8.i18n.nuxtjs.org/)
Expand Down
12 changes: 6 additions & 6 deletions docs/content/1.getting-started/1.setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@
::alert{type="warning"}
❗IMPORTANT

- From this section, this documentation is for Nuxt i18n module (`@nuxtjs/i18n`) v8 beta. if you would like to use v7.x, see the [here](https://i18n.nuxtjs.org/)
- From this section, this documentation is for Nuxt i18n module (`@nuxtjs/i18n`) v8 beta. If you would like to use v7.x, see [here](https://i18n.nuxtjs.org/).

- Nuxt i18n module next is still v8 **beta**, the API might subject to breaking changes. We will make every effort to have the same I/F as v7.x, but Nuxt 3 is a major release, it might not be the same I/F.
- Nuxt i18n module's next version, **v8**, is in beta and still undergoing development. Its API may be subject to changes that could cause compatibility issues. Although the development team will try to maintain the same interface as version 7.x, the upcoming major release of Nuxt 3 may introduce changes that could affect the interface.
::

::alert{type="info"}
Check the [Nuxt.js documentation](https://nuxt.com/docs/guide/concepts/modules) for more information about installing and using modules in Nuxt.js.
Check the [Nuxt documentation](https://nuxt.com/docs/guide/concepts/modules) for more information about installing and using modules in Nuxt.
::

Add `@nuxtjs/i18n` dependency to your project:
Expand All @@ -28,9 +28,9 @@ pnpm add @nuxtjs/i18n@next --save-dev
```
::

Then, add `@nuxtjs/i18n` to the `modules` section in your `nuxt.config.js`. You can use either of the following ways to specify the module options:
Then, add `@nuxtjs/i18n` to the `modules` section in your `nuxt.config`. You can use either of the following ways to specify the module options:

```js {}[nuxt.config.js]
```ts {}[nuxt.config.ts]
export default defineNuxtConfig({
modules: [
'@nuxtjs/i18n',
Expand All @@ -43,7 +43,7 @@ export default defineNuxtConfig({

or

```js {}[nuxt.config.js]
```ts {}[nuxt.config.ts]
export default defineNuxtConfig({
modules: [
[
Expand Down
50 changes: 22 additions & 28 deletions docs/content/1.getting-started/2.basic-usage.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# Basic Usage

The basic to get started with Nuxt i18n module is to translate with Vue I18n via the `vueI18n` option.
The basics to get started with the Nuxt i18n module is to translate with Vue I18n via the `vueI18n` option.

---

## Translate with Vue I18n

The basic to get started with **Nuxt i18n module** is to **translate with Vue I18n via the `vueI18n` option**

So, let's get started configuring the following nuxt config:
So, let's get started configuring the following `nuxt.config`:

```js {}[nuxt.config.js]
```ts {}[nuxt.config.ts]
export default defineNuxtConfig({
modules: [
'@nuxtjs/i18n'
Expand All @@ -33,9 +33,9 @@ export default defineNuxtConfig({
})
```

`vueI18n` option is the same as `createI18n` function option of Vue I18n. `vueI18n` option is passed to the `createI18n` function via the nuxt plugin of this module internally.
The `vueI18n` option is the same as `createI18n` function option of Vue I18n. `vueI18n` option is passed to the `createI18n` function via the nuxt plugin of this module internally.

About detail of `vueI18n` option, see the [Vue I18n documentation](https://vue-i18n.intlify.dev/api/general.html#createi18n)
For more details about the `vueI18n` option, see the [Vue I18n documentation](https://vue-i18n.intlify.dev/api/general.html#createi18n).

Now, put (or edit) the following the page component in `pages` directory of you project:

Expand Down Expand Up @@ -65,47 +65,44 @@ The code demonstrated in this chapter is illustrated using Nuxt [Pages](https://

::alert{type="info"}

Some composable functions provided by @nuxtjs/i18n such as `useI18n` are [auto-imported by Nuxt](https://nuxt.com/docs/guide/concepts/auto-imports#auto-imports)
Some composable functions provided by @nuxtjs/i18n such as `useI18n` are [auto-imported by Nuxt](https://nuxt.com/docs/guide/concepts/auto-imports#auto-imports).

If you want to import them explicitly, you can use `#imports` as follows:


```vue
<script setup>
import { useI18n, useLocalePath } from '#imports'
// ...
</script>
```

::

You have a really simple Vue I18n based translation environment ready to go. You run the above page component in your project, you can see the form that has English or French in select. so you will select a language, you can see the "welcome" in the each language.
You now have a really simple Vue I18n based translation environment ready to go! The `<form>` element that contains both English and French options, choosing either languages from the dropdown, you can see the word "welcome" change in its corresponding language.

you are now ready to localize your application using Vue I18n. Vue I18n also provides several other features.
For more information on Vue I18n, refer to the [docs](https://vue-i18n.intlify.dev/)
For more information about **Vue I18n**, you can refer to its documentation [here](https://vue-i18n.intlify.dev/).


## Link localizing

**Nuxt i18n module** extends the integrated Vue I18n to give us some i18n features for Nuxt application. In here, we introduce one of those features, the link localization with extending Nuxt pages and routing.
The **Nuxt i18n module** extends the integrated Vue I18n to give us some i18n features for Nuxt application. In here, we introduce one of those features, the link localization with extending Nuxt pages and routing.

### Configurations

You will need to additionally set the `defaultLocale` and `locales` options, as in the following configuration.
You'll need to additionally set the `defaultLocale` and `locales` options, as in the following configuration.

In the link localizing, using the codes provided in the `locales` option as the URL path prefix, except for the `defaultLocale` (read more on [routing](/guide/routing-strategies)).
For localizing links, you can use the code provided from the `locales` option as the URL path prefix, except for `defaultLocale` (read more on [routing](/guide/routing-strategies)).


```diff {}[nuxt.config.js]
```diff {}[nuxt.config.ts]
export default defineNuxtConfig({
modules: [
'@nuxtjs/i18n'
],

i18n: {
+ locales: ['en', 'fr'], // used in URL path prefix
+ defaultLocale: 'en', // default locale of your project for Nuxt pages and routings
+ locales: ['en', 'fr'], // used in URL path prefix
+ defaultLocale: 'en', // default locale of your project for Nuxt pages and routings
vueI18n: {
legacy: false,
locale: 'en',
Expand All @@ -122,15 +119,13 @@ In the link localizing, using the codes provided in the `locales` option as the
})
```

When rendering internal links in your app using `<NuxtLink>`, you need to get proper URLs for the current locale. To do this, **Nuxt i18n module** provides some helper composables:
When rendering internal links in your app using `<NuxtLink>`, you need to get proper URLs for the current locale. To do this, the **Nuxt i18n module** provides some helper composables:

### URL path

You can localize URL path with using `useLocalePath`.

`useLocalePath` is a composable function. Calling that composable function returns a function that is able to return the localized URL for a given page.

The first parameter can be either the path or name of the route or an object for more complex routes. A locale code can be passed as the second parameter to generate a link for a specific language:
`useLocalePath` is a composable which returns a function used to get the localized URL for a given page. The first parameter can be either the path or name of the route or an object for more complex routes. A locale code can be passed as the second parameter to generate a link for a specific language:

```vue
<script setup>
Expand All @@ -153,15 +148,15 @@ Note that `localePath` can use the route's unprefixed path, which must start wit

::alert{type="info"}

If you would use Options API style, you can do the same with `this.localePath`. This API is kept for migration from Nuxt2.
If you prefer to use the Options API, you can use `this.localePath`. This API is kept for migration from Nuxt 2.

::

### Language switching path

You can localize language path with using `useSwitchLocalePath`.

`useSwitchLocalePath` is a composable function. Calling that composable function returns a function that is able to return a link to the current page in another language:
`useSwitchLocalePath` is a composable function which returns a link to the current page in another language:

```vue
<script setup>
Expand All @@ -176,22 +171,21 @@ const switchLocalePath = useSwitchLocalePath()

::alert{type="info"}

If you would use Options API style, you can do the same with `this.switchLocalePath`. This API is kept for migration from Nuxt2.
If you prefer to use the Options API, you can use `this.switchLocalePath`. This API is kept for migration from Nuxt 2.

::

### URL path with Route object

You can localize advanced URL path with using `useLocaleRoute`. This is useful if you would to control internal link programmatically.

`useLocaleRoute` is a composable function. Calling that composable function returns a function that is able to return the `Route` object for a given page.
`useLocaleRoute` is a composable function that returns a `Route` object for a given page.

It works like `useLocalePath` but returns route resolved by Vue Router rather than just a full route path. This can be useful since full path returned from `useLocalePath` might not carry all information from provided input (for example the route params that the page doesn't specify).
It works like `useLocalePath` but returns route resolved by Vue Router rather than just a full route path. This can be useful since full path returned from `useLocalePath` might not carry all information from the provided input (for example, the route params that the page doesn't specify).

```vue
<script setup>
const localeRoute = useLocaleRoute()
function onClick() {
const route = localeRoute({ name: 'user-profile', query: { foo: '1' } })
if (route) {
Expand All @@ -207,6 +201,6 @@ function onClick() {

::alert{type="info"}

If you would use Options API style, you can do the same with `this.localeRoute`. This API is kept for migration from Nuxt2.
If you prefer to use the Options API, you can use `this.localeRoute`. This API is kept for migration from Nuxt 2.

::

0 comments on commit 4aeeeec

Please sign in to comment.