博客Dashboard
Inline Translations

useMessages

useMessages() 字符串翻译函数的 API 参考

概览

useMessages 函数是一个在构建时将来自 msg 的 encoded string 翻译的 Hook。

const m = useMessages();

<p>{  m(encodedString)  }</p>;

构建时翻译： useMessages 的翻译在构建阶段完成，先于应用部署。 你可以从 msg 传入编码字符串，它们会被翻译为用户的首选语言。

参考资料

参数

无

返回值

一个回调函数 m，用于翻译 msg 中提供的编码内容。

(encodedContent: string, options?: Record<string, any>) => string
名称类型描述
encodedContentstring来自 msg 的待翻译编码字符串内容。
options?Record<string, any>可选参数，用于向该编码字符串传入变量。

行为

生产环境

在 CD 过程中，任何位于 msg 函数内的内容都会在应用部署前完成翻译。 这可确保所有 locale 的快速加载，但它只能翻译构建时已知的内容。

生成后，翻译内容将根据你的配置（1）存储在 CDN（内容分发网络）中，或（2）存储在应用的构建输出中。 随后，这些翻译内容会提供给你的用户。 如果未找到翻译，则会回退到原始内容。

请务必遵循此处的部署指南。

开发

在开发阶段，m 函数会按需翻译内容。 这有助于你为应用在不同语言下的呈现效果做原型验证。 请记得在环境中添加 Dev API key 以启用此行为。

在开发环境中进行按需翻译时，你会看到一定的延迟。 除非内容被明确设置为按需翻译， 否则在生产构建中不会出现这种情况， 例如使用 tx 或 <Tx> 时。

示例

基本用法

你可以使用 useMessages 翻译来自 msg 的 encoded string。

import { msg, useMessages } from 'gt-react';

const encodedGreeting = msg('你好，Alice！');

export default function TranslateGreeting() {
  const m = useMessages();

  return (
    <p>
      {m(encodedGreeting)}
    </p>
  );
}

注意：“Alice”将会翻译为用户偏好的语言。

使用变量

你可以向编码字符串传入变量。

import { msg, useMessages } from 'gt-react';

const encodedGreeting = msg('你好，{name}！');

export default function TranslateGreeting() {
  const m = useMessages();

  return (
    <p>
      {m(encodedGreeting, { name: 'Bob' })} {/* 将显示"你好，Bob！" */}
    </p>
  );
}

msg 变量会覆盖 m 变量

当同时向 msg 和 m 传入变量时，传给 msg 的变量会覆盖传给 m 的变量。

import { msg, useMessages } from 'gt-react';

const encodedGreeting = msg('你好，{name}！', { name: 'Alice' });

export default function TranslateGreeting() {
  const m = useMessages();
  return (
    <p>
      {m(encodedGreeting, { name: 'Bob' })}
    </p>
  );
}

注意：这将显示 "Hello, Alice!" —— 变量在渲染时不会被重新赋值。

使用 ICU 消息格式

gt-react 支持 ICU 消息格式，可用于对变量进行格式化。

import { msg, useMessages } from 'gt-react';

const encodedMessage = msg('购物车中{count, plural, =0 {没有商品} =1 {有1件商品} other {有{count}件商品}}', { count: 10 });

export default function TranslateGreeting() {
  const m = useMessages();
  return (
    <p>
      {m(encodedMessage)}
    </p>
  );
}

ICU 消息格式是用于格式化变量的强大方式。 了解更多，请参阅ICU 消息格式文档。

备注

  • useMessages 函数是一个 hook，用于将来自 msg 的 encoded string 进行 translate。
  • 使用 useMessages 的翻译会在运行时之前、于构建阶段完成（开发环境除外）。

后续步骤

  • 参阅 getMessages，在构建时从 encoded string 异步获取翻译。
  • 参阅 msg，用于将字符串编码以便翻译。
  • 如需运行时翻译，请参阅 tx 和 <Tx>。

本指南如何?

msg

msg() 字符串函数 API 参考

useTranslations

useTranslations 钩子的 API 参考

本页目录

概览
参考资料
参数
返回值
行为
生产环境
开发
示例
基本用法
使用变量
msg 变量会覆盖 m 变量
使用 ICU 消息格式
备注
后续步骤