---
url: /plugins/i18n.md
---
# Internationalization {#i18n}

![NPM Version](https://img.shields.io/npm/v/%40winner-fed%2Fplugin-locale?style=flat-square\&colorB=646cff)

Internationalization plugin based on [Vue I18n](https://vue-i18n.intlify.dev/guide/), which can easily integrate internationalization functionality into your WinJS applications. Compatible with Vue 3.

## Setup

1. Install the plugin

::: code-group

```bash [NPM]
$ npm add @winner-fed/plugin-locale -D
```

```bash [YARN]
$ yarn add @winner-fed/plugin-locale -D
```

```bash [PNPM]
$ pnpm add @winner-fed/plugin-locale -D
```

```bash [BUN]
$ bun add @winner-fed/plugin-locale -D
```

:::

2. Enable this feature in the `.winrc` configuration file

```ts
import { defineConfig } from 'win';

export default defineConfig({
  plugins: ['@winner-fed/plugin-locale'],
  /**
   * @name Internationalization plugin
   * @description Locale plugin based on vue-i18n
   * @doc https://winjs-dev.github.io/winjs-docs/plugins/i18n.html
   */
  locale: {},
  // Or use the i18n field for configuration
});
```

## Getting Started

The internationalization plugin uses a conventional directory structure. We conventionally introduce multi-language files in the `src/locales[i18n]` directory.

The naming of multi-language files must follow this specification: `<lang><separator><COUNTRY>.(js|json|ts)`. Where `<separator>` is the separator, which defaults to `-` and can be configured through the `baseSeparator` option.

For example, if you need to introduce multi-language support for Simplified Chinese and English in your project, you can create two files `zh-CN.ts` and `en-US.ts` in the `src/locales` directory:

```diff
src
  + locales
    + zh-CN.ts
    + en-US.ts
  pages
```

Configure the internationalization plugin in `.winrc.ts`:

```ts
export default {
  locale: {
    // Use src/locales/zh-CN.ts as the default multi-language file
    default: 'zh-CN',
    baseSeparator: '-',
  },
};
```

For more information about configuration, see the [Plugin Configuration](#plugin-configuration) section.

Now, add your first multi-language content:

```ts
// src/locales/zh-CN.ts
export default {
  welcome: '欢迎光临 WinJS 的世界！',
};
```

```ts
// src/locales/en-US.ts
export default {
  welcome: "Welcome to WinJS's world!",
};
```

```ts
// src/locales/zh-TW.ts
export default {
  welcome: "歡迎光臨 WinJS 的世界！",
};
```

You can also use `.json` files to store multi-language content:

```json
// src/locales/zh-CN.json
{
  "welcome": "欢迎光临 WinJS 的世界！"
}

// src/locales/en-US.json
{
  "welcome": "Welcome to WinJS's world!"
}

// src/locales/zh-TW.json
{
  "welcome": "歡迎光臨 WinJS 的世界！"
}
```

Everything is ready. Now you can use multi-language content in WinJS.

```vue
<template>
  <div>
    <h2>Hi! Welcome to Winjs ❤️ Vue!</h2>
    <p>
      <img src="@/assets/img/logo.png" width="200" height="200" alt="logo" />
    </p>
    <div>
      {{ t('welcome') }}
    </div>
    <div>
      <button @click="setLocale('en-US')"
      >en-US</button
      >
      <br>
      <button @click="setLocale('zh-CN')"
      >zh-CN</button
      >
      <br>
      <button @click="setLocale('zh-TW')"
      >zh-TW</button
      >
    </div>
    <p>To get started, edit <code>pages/index.vue</code> and save to reload.</p>
  </div>
</template>

<script setup lang="ts">
import { setLocale, useI18n } from 'winjs';
const { t, locale } = useI18n();
</script>
```

The rendered result is as follows:

```html
<!-- zh-CN -->
<div>欢迎光临 WinJS 的世界！</div>

<!-- en-US -->
<div>Welcome to WinJS's world!</div>

<!-- zh-TW -->
<div>歡迎光臨 WinJS 的世界！</div>
```

## Switching Languages

The provided `setLocale()` interface can help you quickly add language switching functionality to your project.

```ts
import { setLocale } from 'winjs';

setLocale('en-US');
```

If you need to switch to the default language, simply call this method without passing any parameters:

```ts
// If your default language is zh-CN
// Then the following call has the same effect as setLocale('zh-CN')
setLocale();
```

## Common API Introduction

### `addLocale` Dynamically Add Multi-language Support

Without creating and writing separate multi-language files, you can use the `addLocale()` interface to dynamically add language support at runtime. It accepts two parameters:

| Parameter      | Type     | Description                                  |
| --------- | -------- |-------------------------------------|
| `locale`    | `String` | The name of the multi-language, a name that conforms to the `<lang>-<COUNTRY>` specification |
| `messages` | `Object` | The content object of the multi-language                            |

For example, if you want to dynamically introduce multi-language support for Japanese, you can write the code as follows:

```ts
import { addLocale } from 'winjs';

addLocale({ locale: 'ja-JP', messages: { lang: '言語', test: 'テスト' } });
```

### `setLocale` Set Language

The `setLocale()` interface can be used to programmatically set the current language dynamically. It has one parameter:

| Parameter         | Type      | Description                                       |
| ------------ | --------- | ------------------------------------------ |
| `lang`       | `String`  | The language to switch to                               |

```ts
import { setLocale } from 'winjs';

setLocale('en-US');
```

### useI18n

Composition API, can only be used in the `setup` function. For more details, refer to [Vue I18n](https://vue-i18n.intlify.dev/api/composition.html#usei18n).
Example:

```vue
<template>
  <div>
    {{ t('lang') }}:
    {{ t('test') }}
  </div>
</template>

<script lang="ts" setup>
import { useI18n } from 'winjs';

const { t, locale } = useI18n();
</script>
```

`useI18n()` returns a [Composer](https://vue-i18n.intlify.dev/api/composition.html#composer), which provides conversion functions like `t`, `n`, `d`, etc., for use in templates.

## Plugin Configuration

You can configure the internationalization plugin in `.winrc.ts`. The default values are as follows:

```ts
export default {
  locale: {
    baseSeparator: '-',
    default: 'zh-CN'
  },
};
```

Detailed configuration descriptions are as follows:

| Configuration Item | Type | Default Value | Description |
| --- | --- | --- | --- |
| `baseSeparator` | `String` | `-` | The **separator** between Language and Country. By default, it is `-`, and the returned language and directory files are `zh-CN`, `en-US`, `sk`, etc. If specified as `_`, then `default` defaults to `zh_CN`. |
| `default` | `String` | `zh-CN` | The project's **default language**. When a specific language cannot be detected, the default language set in `default` is used. |