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. 在配置文件中 .winrc 中开启该功能

import { defineConfig } from 'win';

export default defineConfig({
  plugins: ['@winner-fed/plugin-locale'],
  /**
   * @name 国际化插件
   * @description 基于 vue-i18n 的请求插件
   * @doc https://winjs-dev.github.io/winjs-docs/plugins/i18n.html
   */
  locale: {},
  // 或使用 i18n 字段配置
});

开始使用

国际化插件采用约定式目录结构，我们约定在 src/locales[i18n] 目录下引入多语言文件。

多语言文件的命名需遵循此规范：<lang><separator><COUNTRY>.(js|json|ts)。其中，<separator> 为分隔符，默认为 -，可以通过 baseSeparator 项配置。

例如，如果您需要在项目中引入简体中文和英文的多语言支持，可以在 src/locales 目录下创建 zh-CN.ts 和 en-US.ts 两个文件：

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

在 .winrc.ts 中配置国际化插件：

export default {
  locale: {
    // 默认使用 src/locales/zh-CN.ts 作为多语言文件
    default: 'zh-CN',
    baseSeparator: '-',
  },
};

关于配置的更多介绍可参见配置插件章节。

现在，添加您的第一条多语言内容：

// 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 的世界！",
};

您也可以使用 .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 的世界！"
}

一切就绪，现在您可以在 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>

渲染的结果如下：

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

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

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

切换语言

通过提供的 setLocale() 接口可以帮助您快速地向项目中添加切换语言的功能。

import { setLocale } from 'winjs';

setLocale('en-US');

如果需要切换为默认的语言，只需要调用此方法而不用传递任何参数：

// 如果您的默认语言为 zh-CN
// 那么以下调用具有与 setLocale('zh-CN') 同样的效果
setLocale();

常用接口介绍

addLocale 动态添加多语言支持

无需创建并编写单独的多语言文件，使用 addLocale() 接口可以在运行时动态添加语言支持。它接受两个参数：

参数	类型	介绍
locale	String	多语言的名称, 符合 <lang>-<COUNTRY> 规范的名称
messages	Object	多语言的内容对象

例如，您想要动态引入繁体中文的多语言支持，可以编写代码如下：

import { addLocale } from 'winjs';

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

setLocale 设置语言

通过 setLocale() 接口可以使用编程的方法动态设置当前的语言。它有两个参数：

参数	类型	介绍
lang	String	切换到的语言

import { setLocale } from 'winjs';

setLocale('en-US');

useI18n

Composition API, 只能在 setup 函数中使用，更多细节参考 Vue I18n。  举个 🌰：

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

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

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

useI18n()返回结果是 Composer，提供类似 t、n、d 等转换函数，在模板中使用。

配置插件

您可以在 .winrc.ts 中配置国际化插件。默认值如下：

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

配置的详细介绍如下：

配置项	类型	默认值	介绍
baseSeparator	String	-	语言（Language）与国家（Country） 之间的分割符。默认情况下为 -，返回的语言及目录文件为 zh-CN、en-US 和 sk 等。若指定为 _，则 default 默认为 zh_CN。
default	String	zh-CN	项目默认语言。当检测不到具体语言时，使用 default 设置的默认语言。