MK
摩柯社区 - 一个极简的技术知识社区
AI 面试

Qwik国际化支持：多语言应用的实现路径

2022-03-144.3k 阅读

Qwik 国际化基础

为什么要在 Qwik 中实现国际化

在当今全球化的互联网环境下，构建多语言应用变得至关重要。用户遍布世界各地，不同地区的用户习惯使用自己熟悉的语言与应用交互。通过实现国际化，应用可以：

  1. 扩大受众群体：吸引更多非母语用户，增加用户数量。
  2. 提升用户体验：使用户能以自己熟悉的语言操作应用，提高满意度和忠诚度。
  3. 符合商业需求：对于面向全球市场的商业应用，多语言支持是必要的竞争优势。

Qwik 国际化的基本概念

  1. 语言文件：在 Qwik 中，通常会为每种支持的语言创建单独的语言文件。这些文件一般采用 JSON 格式，用于存储不同语言的文本内容。例如，一个简单的英文语言文件 en.json 可能如下：
{
  "welcome": "Welcome to our app",
  "login": "Login",
  "logout": "Logout"
}

而对应的中文语言文件 zh.json 可能是：

{
  "welcome": "欢迎来到我们的应用",
  "login": "登录",
  "logout": "注销"
}

  1. 语言切换机制：Qwik 需要提供一种机制来让用户能够切换应用的语言。这通常涉及到在应用中某个地方提供语言选择的界面元素，比如下拉菜单或按钮，并根据用户的选择动态更新应用的语言。

  2. 上下文感知：应用需要能够根据用户的操作或设备设置等上下文信息，自动选择合适的语言。例如，根据浏览器的语言设置，优先显示用户设备偏好的语言。

配置 Qwik 项目以支持国际化

安装必要的依赖

在 Qwik 项目中，我们可以使用 @qwik-i18n 库来简化国际化的实现。首先，通过 npm 或 yarn 安装该库：

npm install @qwik-i18n
# 或者
yarn add @qwik-i18n

创建语言文件结构

在项目的 src 目录下，创建一个 locales 目录。在 locales 目录中，为每种支持的语言创建一个子目录，例如 en、zh、fr 等。在每个语言子目录中，创建一个 messages.json 文件，用于存储该语言的文本内容。例如，src/locales/en/messages.json：

{
  "home_title": "Home Page",
  "product_list": "Product List",
  "contact_us": "Contact Us"
}

src/locales/zh/messages.json：

{
  "home_title": "首页",
  "product_list": "产品列表",
  "contact_us": "联系我们"
}

配置 Qwik 加载语言文件

在 Qwik 的配置文件（通常是 qwik.config.ts）中，我们需要配置如何加载语言文件。首先导入必要的模块：

import { defineConfig } from '@builder.io/qwik'
import { qwikI18n } from '@qwik-i18n'

const locales = ['en', 'zh']

export default defineConfig(() => {
  return {
    integrations: [
      qwikI18n({
        locales,
        defaultLocale: 'en',
        loaders: {
          en: () => import('./src/locales/en/messages.json'),
          zh: () => import('./src/locales/zh/messages.json')
        }
      })
    ]
  }
})

在上述配置中，我们定义了支持的语言列表 locales，设置了默认语言 defaultLocale，并通过 loaders 配置了如何加载每种语言的消息文件。

在 Qwik 组件中使用国际化

注入翻译函数

在 Qwik 组件中，我们可以通过 inject 函数注入翻译函数。首先，从 @qwik-i18n 中导入 useTranslations 钩子：

import { component$, useTranslations } from '@qwik-i18n'

export const MyComponent = component$(() => {
  const { t } = useTranslations('common')
  return (
    <div>
      <h1>{t('home_title')}</h1>
      <p>{t('product_list')}</p>
      <a href="#">{t('contact_us')}</a>
    </div>
  )
})

在上述代码中，useTranslations 函数接受一个命名空间参数 common。命名空间可以用于组织不同模块的翻译文本，例如，你可以有 common 命名空间用于通用文本，product 命名空间用于产品相关文本等。t 函数用于获取翻译后的文本，它接受一个键作为参数，这个键对应语言文件中的键。

动态切换语言

为了实现语言的动态切换，我们可以在组件中添加语言选择的界面元素，并通过 setLocale 函数来更新应用的语言。首先，从 @qwik-i18n 中导入 setLocale 函数：

import { component$, useTranslations, setLocale } from '@qwik-i18n'

export const LanguageSelector = component$(() => {
  const { t } = useTranslations('common')
  const changeLanguage = (lang: string) => {
    setLocale(lang)
  }

  return (
    <div>
      <select onChange={(e) => changeLanguage(e.target.value as string)}>
        <option value="en">English</option>
        <option value="zh">中文</option>
      </select>
      <p>{t('language_selected')}</p>
    </div>
  )
})

在上述代码中，changeLanguage 函数接受一个语言代码作为参数，并调用 setLocale 函数来更新应用的语言。select 元素的 onChange 事件绑定了 changeLanguage 函数，当用户选择不同的语言选项时，应用的语言会相应更新。

处理复数和性别等复杂情况

在某些语言中，需要根据数量或性别等因素来选择不同的翻译文本。例如，在英语中，“1 item” 和 “2 items” 的表述不同。在 Qwik 中，我们可以利用 @qwik-i18n 的功能来处理这种情况。

首先，在语言文件中定义复数形式的文本。例如，在 en.json 中：

{
  "item_count": {
    "one": "1 item",
    "other": "{{count}} items"
  }
}

在 zh.json 中：

{
  "item_count": {
    "one": "1 个项目",
    "other": "{{count}} 个项目"
  }
}

然后，在组件中使用 t 函数并传入数量参数：

import { component$, useTranslations } from '@qwik-i18n'

export const ItemCountComponent = component$(() => {
  const { t } = useTranslations('common')
  const itemCount = 5
  return (
    <p>{t('item_count', { count: itemCount })}</p>
  )
})

在上述代码中，t 函数会根据 itemCount 的值选择合适的翻译文本。如果 itemCount 为 1，会选择 one 对应的文本；否则，选择 other 对应的文本，并将 count 参数替换到文本中。

基于上下文的语言选择

根据浏览器语言设置选择语言

Qwik 可以根据浏览器的语言设置自动选择合适的语言。我们可以在应用的入口文件（通常是 main.tsx）中添加如下代码：

import { render } from '@builder.io/qwik'
import { detectLocale } from '@qwik-i18n'
import { App } from './App'

const browserLang = navigator.language.split('-')[0]
const locale = detectLocale(browserLang, ['en', 'zh'])

render(() => <App />, {
  initialLocale: locale
})

在上述代码中，navigator.language 获取浏览器的语言设置，detectLocale 函数从支持的语言列表中选择最匹配的语言。然后，通过 render 函数的 initialLocale 参数将选择的语言传递给应用。

根据用户设置存储语言偏好

除了根据浏览器语言设置，我们还可以让用户手动选择语言并将其偏好存储起来。一种常见的方式是使用 localStorage。在语言切换函数中，我们可以同时将用户选择的语言存储到 localStorage 中：

import { component$, useTranslations, setLocale } from '@qwik-i18n'

export const LanguageSelector = component$(() => {
  const { t } = useTranslations('common')
  const changeLanguage = (lang: string) => {
    setLocale(lang)
    localStorage.setItem('user-locale', lang)
  }

  return (
    <div>
      <select onChange={(e) => changeLanguage(e.target.value as string)}>
        <option value="en">English</option>
        <option value="zh">中文</option>
      </select>
      <p>{t('language_selected')}</p>
    </div>
  )
})

然后，在应用的入口文件中，我们可以从 localStorage 中读取用户的语言偏好，并以此作为初始语言：

import { render } from '@builder.io/qwik'
import { App } from './App'

const userLocale = localStorage.getItem('user-locale')
const initialLocale = userLocale || 'en'

render(() => <App />, {
  initialLocale
})

这样，用户下次打开应用时，会显示其上次选择的语言。

国际化与路由的结合

基于路由的语言切换

在多语言应用中，我们可能希望通过 URL 来表示当前的语言。例如，/en/home 表示英文的首页，/zh/home 表示中文的首页。在 Qwik 中，我们可以结合路由来实现这种功能。

首先，在路由配置中添加语言参数。假设我们使用 @builder.io/qwik-city 进行路由管理，在 routes.ts 中：

import { defineRoutes } from '@builder.io/qwik-city'

export default defineRoutes((route) => {
  route('/:locale/home', () => import('./HomePage'))
  // 其他路由...
})

然后，在组件中获取路由参数并根据其切换语言。在 HomePage.tsx 中：

import { component$, useRouteParams, useTranslations, setLocale } from '@qwik-i18n'

export const HomePage = component$(() => {
  const { locale } = useRouteParams()
  const { t } = useTranslations('common')

  if (locale) {
    setLocale(locale)
  }

  return (
    <div>
      <h1>{t('home_title')}</h1>
      {/* 其他内容... */}
    </div>
  )
})

在上述代码中，useRouteParams 函数获取路由参数中的语言代码 locale，然后通过 setLocale 函数更新应用的语言。

生成多语言的路由链接

当应用中有导航链接时，我们需要根据当前语言生成对应的链接。例如，在英文页面中，导航到首页的链接应该是 /en/home，在中文页面中应该是 /zh/home。

我们可以创建一个自定义的链接生成函数。在 utils.ts 中：

import { getLocale } from '@qwik-i18n'

export const generateLocaleLink = (path: string) => {
  const locale = getLocale()
  return `/${locale}${path}`
}

然后，在组件中使用这个函数生成链接。在 Navigation.tsx 中：

import { component$ } from '@builder.io/qwik'
import { generateLocaleLink } from './utils'

export const Navigation = component$(() => {
  return (
    <nav>
      <a href={generateLocaleLink('/home')}>Home</a>
      <a href={generateLocaleLink('/products')}>Products</a>
    </nav>
  )
})

这样，生成的链接会根据当前应用的语言自动添加正确的语言前缀。

测试 Qwik 国际化应用

单元测试翻译函数

在 Qwik 应用中，我们可以使用测试框架（如 Vitest）来测试翻译函数是否正常工作。首先，安装必要的依赖：

npm install --save-dev vitest @qwik-i18n/testing-library

然后，创建一个测试文件，例如 MyComponent.test.tsx：

import { render } from '@qwik-i18n/testing-library'
import { MyComponent } from './MyComponent'

describe('MyComponent', () => {
  it('should render translated text in English', () => {
    const { getByText } = render(<MyComponent />, { locale: 'en' })
    expect(getByText('Home Page')).toBeInTheDocument()
  })

  it('should render translated text in Chinese', () => {
    const { getByText } = render(<MyComponent />, { locale: 'zh' })
    expect(getByText('首页')).toBeInTheDocument()
  })
})

在上述测试中，我们使用 @qwik-i18n/testing-library 的 render 函数来渲染组件，并通过设置 locale 参数来测试不同语言下组件的渲染情况。

集成测试语言切换

为了测试语言切换功能，我们可以使用测试框架（如 Cypress）来进行集成测试。首先，安装 Cypress：

npm install --save-dev cypress

然后，在 cypress/e2e 目录下创建一个测试文件，例如 languageSwitching.test.ts：

describe('Language Switching', () => {
  it('should switch language from English to Chinese', () => {
    cy.visit('/en/home')
    cy.get('select').select('zh')
    cy.contains('首页').should('be.visible')
  })

  it('should switch language from Chinese to English', () => {
    cy.visit('/zh/home')
    cy.get('select').select('en')
    cy.contains('Home Page').should('be.visible')
  })
})

在上述测试中，我们使用 Cypress 模拟用户在应用中切换语言，并验证页面上的文本是否根据语言切换而正确更新。

优化 Qwik 国际化应用的性能

代码拆分与懒加载语言文件

在 Qwik 中，我们可以利用代码拆分和懒加载来优化语言文件的加载性能。在 qwik.config.ts 中，我们已经配置了语言文件的加载方式。通过这种方式，只有在需要时才会加载特定语言的文件。

例如，假设用户在应用启动时使用的是英文，只有当用户切换到中文时，才会加载 zh.json 文件。这种懒加载机制可以减少应用的初始加载时间，特别是对于支持多种语言的应用。

缓存翻译结果

为了提高性能，我们可以缓存翻译结果。在组件中，我们可以使用 JavaScript 的 Map 数据结构来缓存已经翻译过的文本。例如：

import { component$, useTranslations } from '@qwik-i18n'

export const MyComponent = component$(() => {
  const { t } = useTranslations('common')
  const translationCache = new Map<string, string>()

  const getTranslatedText = (key: string) => {
    if (translationCache.has(key)) {
      return translationCache.get(key)
    }
    const translatedText = t(key)
    translationCache.set(key, translatedText)
    return translatedText
  }

  return (
    <div>
      <h1>{getTranslatedText('home_title')}</h1>
      <p>{getTranslatedText('product_list')}</p>
    </div>
  )
})

在上述代码中，translationCache 缓存了已经翻译过的文本。当再次需要翻译相同的键时，直接从缓存中获取，避免了重复的翻译操作，从而提高了性能。

预加载语言文件

在某些情况下，我们可能知道用户很可能会切换到某些语言，这时可以进行预加载。例如，在应用启动时，如果检测到用户设备的语言为中文，但应用当前使用的是英文，我们可以预加载中文语言文件。

在 main.tsx 中：

import { render } from '@builder.io/qwik'
import { detectLocale, preloadLocale } from '@qwik-i18n'
import { App } from './App'

const browserLang = navigator.language.split('-')[0]
const currentLocale = 'en'
const possibleLocale = detectLocale(browserLang, ['en', 'zh'])

if (currentLocale!== possibleLocale) {
  preloadLocale(possibleLocale)
}

render(() => <App />, {
  initialLocale: currentLocale
})

在上述代码中，preloadLocale 函数预加载了可能需要的语言文件，这样当用户切换语言时，加载速度会更快，提升了用户体验。