Internationalization

Internationalization plugin based on Vue I18n, which can easily integrate internationalization functionality into your WinJS applications. Compatible with Vue 3.

Setup

1. Install the plugin

NPM

$ npm add @winner-fed/plugin-locale -D

YARN

$ yarn add @winner-fed/plugin-locale -D

PNPM

$ pnpm add @winner-fed/plugin-locale -D

BUN

$ bun add @winner-fed/plugin-locale -D

2. Enable this feature in the .winrc configuration file

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:

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

Configure the internationalization plugin in .winrc.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 section.

Now, add your first multi-language content:

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

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

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

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

// 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.

<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:

<!-- 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.

import { setLocale } from 'winjs';

setLocale('en-US');

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

// 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:

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

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. Example:

<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, 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:

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.