WordPress.com Calypso Community Translator 组件指南:界面语言切换与社区翻译启动器
WordPress.com Calypso Community Translator 组件指南:界面语言切换与社区翻译启动器
本指南基于 wp-calypso 仓库中 client/layout/community-translator/README.md 及其配套实现,系统讲解 WordPress.com 前端(Calypso)如何通过 Community Translator Launcher 组件,让使用非英语界面语言的用户一键开启或关闭“社区翻译”模式,并基于 GlotPress(translate.wordpress.com)完成页面文案的众包翻译。阅读本文后,你将掌握该组件的挂载方式、显示条件、激活/停用流程、与 i18n-calypso 翻译管道的对接原理,以及如何借助翻译扫描器(Translation Scanner)与共情模式(Empathy Mode)进行翻译质量审查与调试。
一、组件定位:一个常驻屏幕右下角的翻译开关
Community Translator(社区翻译器)是 Calypso 国际化体系中的一个关键交互组件:它不是自动翻译工具,而是为具备翻译权限的社区贡献者提供的一个“就地翻译”工作台开关。用户打开它后,页面上已翻译的文案会被包上一层可供识别的 data-* 标记,用户可以直接在页面上下文里对未翻译或翻译不佳的字符串发起翻译。
1.1 目录结构与职责划分
社区翻译器相关代码集中在一个小型目录中,职责划分非常清晰:
| 文件 | 职责 |
|---|---|
| README.md | 组件说明文档 |
| index.jsx | 入口封装,根据配置决定是否渲染启动器 |
| launcher.jsx | 启动器核心组件(约 400 行),承载全部交互逻辑 |
| style.scss | 启动器、高亮框、提交栏与弹窗的样式 |
其中真正的业务逻辑集中在 launcher.jsx 的 TranslatorLauncher 类组件中,而 index.jsx 只是一个非常薄的入口:
export default function CommunityTranslatorMain() {
if ( config( 'restricted_me_access' ) ) {
return <CommunityTranslatorLauncher />;
}
return null;
}
从源码看,入口还叠加了一层 restricted_me_access 配置开关,只有该配置为真时才渲染启动器,否则组件返回 null(什么都不渲染)。
1.2 启动器在全局布局中的挂载方式
CommunityTranslatorMain 并非由某个具体页面自行引用,而是由全局布局统一异步加载。在 client/layout/index.jsx 中可以看到它被定义为一个按需加载的 chunk:
const loadCommunityTranslator = () =>
import(
/* webpackChunkName: "async-load-calypso-layout-community-translator" */ 'calypso/layout/community-translator'
);
并在布局主体的末尾通过 AsyncLoad 挂载(见 client/layout/index.jsx):
<AsyncLoad require={ loadCommunityTranslator } placeholder={ null } />
这种设计意味着:社区翻译器的代码不会进入主包,而是被拆分成独立的异步 chunk,只有满足条件(配置开启且用户场景匹配)时才真正下载并渲染,对大多数普通用户来说几乎零开销。
二、启动器的可见性与显示条件
README 对启动器的可见性给出了三条硬性条件,对应到源码(launcher.jsx 与 client/lib/translator-jumpstart/index.jsx)中分别是:
- 用户在设置中开启了翻译器选项(用户设置中的
enable_translator项); - 用户使用的是非英语界面语言;
- 浏览器环境可用:屏幕不能太小、不能是触屏设备(作为“拥有右键鼠标”的近似判断)。
这三条条件并非一次性静态判断,而是由 translator.isEnabled() 在初始化后持续生效。其完整判断链在 client/lib/translator-jumpstart/index.jsx 的 isEnabled() 中实现:
isEnabled() {
const currentUser = _user;
// 1. 非英语用户:语言必须是可被翻译的 locale
if ( ! currentUser || ! currentUser.localeSlug || ! canBeTranslated( currentUser.localeSlug ) ) {
return false;
}
// 2. 语言变体(localeVariant)没有对应的官方 GlotPress 翻译集时禁用
if ( currentUser.localeVariant && ! canBeTranslated( currentUser.localeVariant ) ) {
return false;
}
// 3. 用户设置尚未加载完成时禁用
if ( ! _isUserSettingsReady ) {
return false;
}
// 4. 用户未在设置页开启翻译器时禁用
if ( ! _isTranslatorEnabled ) {
return false;
}
// 5. 移动端/触屏设备暂不支持,禁用
if ( ! communityTranslatorJumpstart.isValidBrowser() ) {
return false;
}
return true;
}
对应 README 中“visible when the user has enabled the Community Translator, and is using a non-English interface language”,以及“hidden if the browser has a small screen or touch capabilities”的描述,代码中 isValidBrowser() 直接复用了 @automattic/viewport 的 isMobile() 判断:
isValidBrowser() {
if ( isMobile() ) {
return false;
}
return true;
}
需要特别注意的是 README 中“non-English interface language”在实现上的精确含义:canBeTranslated( currentUser.localeSlug ) 同时排除了英语本身和“虽然非英语但还没有官方翻译集”的语言,例如 de_formal 这类需要映射到 formal 翻译集的变体。此外,如果用户尚未在设置中开启翻译器(_isTranslatorEnabled 为假),即使语言条件满足,启动器也不会出现——这个开关对应设置页中的 “Enable on page translation” 选项。
2.1 状态机的两个关键概念:Enabled 与 Activated
在 client/lib/translator-jumpstart/index.jsx 的注释中,作者明确区分了两个极易混淆的状态:
- Enabled(启用):用户在设置页选择了开启翻译器,但在用户设置数据加载完成之前保持为 false;
- Activated(激活):用户已经点击了启动器按钮,翻译处于打开状态,此时
wrapTranslation()会为 i18n 输出的翻译文本包上data-*标记。
TranslatorLauncher 的组件状态与全局状态通过 getDerivedStateFromProps 保持同步(见 launcher.jsx):
static getDerivedStateFromProps( nextProps, prevState ) {
translator.init( nextProps.currentUser, nextProps.isUserSettingsReady );
trackTranslatorStatus( nextProps.isTranslatorEnabled );
if ( prevState.isEnabled !== translator.isEnabled() ) {
return { ...prevState, isEnabled: translator.isEnabled() };
}
return null;
}
同时,trackTranslatorStatus 会在用户开关翻译器设置时上报 Tracks 事件(calypso_community_translator_enabled / calypso_community_translator_disabled),用于数据分析。
2.2 启动器的 UI 形态与样式
从 style.scss 可以看出,启动器是一个固定在屏幕右下角的胶囊形按钮:
.community-translator {
position: fixed;
bottom: 66px;
right: 24px;
border-radius: 27px;
background: var(--color-primary);
cursor: pointer;
padding: 4px;
font-size: $font-body-small;
z-index: z-index("root", ".community-translator");
&.is-active {
background: var(--color-accent);
}
&.is-incompatible {
background: var(--color-neutral-5);
border: 1px solid var(--color-neutral-10);
}
}
按钮在三种状态下有三种视觉表达:
- 默认状态:主色(
--color-primary)背景; - 激活状态(
is-active):强调色(--color-accent)背景,提示用户翻译已开启; - 不兼容状态(
is-incompatible):灰色背景并加边框,此时按钮功能切换为“Empathy Mode”的控制入口。
按钮内部的文字默认宽度为 0、超出隐藏,仅显示一个 globe(地球)Gridicon 图标;当鼠标悬停时文字才会展开(transition: all 0.15s ease-in-out),这是典型的“图标常驻、文字按需展开”的浮动按钮设计(见 style.scss)。
三、Launcher 的交互流程:从点击到激活
TranslatorLauncher 的核心交互围绕 translator.toggle() 展开(见 launcher.jsx):
toggle = ( event ) => {
event.preventDefault();
const { isEmpathyModeEnabled } = this.props;
if ( isEmpathyModeEnabled ) {
this.toggleEmpathyMode();
return;
}
const nextIsActive = translator.toggle();
bumpStat( 'calypso_translator_toggle', nextIsActive ? 'on' : 'off' );
this.setState( { isActive: nextIsActive } );
};
注意这里有一个交互上的特殊设计:当用户开启了 Empathy Mode 时,启动器按钮不再切换翻译器,而是切换共情模式的开关,避免两种“就地修改文案”的模式同时生效互相干扰。
3.1 底层激活/停用实现
translator.toggle() 的定义在 client/lib/translator-jumpstart/index.jsx。首次点击时,它会先通过 loadjQueryDependentScript 从 CDN 注入社区翻译器脚本:
if ( 'undefined' === typeof window.communityTranslator ) {
loadjQueryDependentScript( injectUrl, function ( error ) {
if ( error || ! window.communityTranslator ) {
debug( 'Script ' + injectUrl + ' failed to load.' );
return;
}
window.communityTranslator.registerTranslatedCallback(
communityTranslatorJumpstart.updateTranslation
);
activate();
} );
return false;
}
脚本注入 URL 由 setInjectionURL 拼接(client/lib/translator-jumpstart/index.jsx),指向 https://widgets.wp.com/community-translator/community-translator.min.js?v=1.160729,并带有固定的版本号参数。
脚本加载成功并注册好回调后,执行 activate():
function activate() {
// Wrap DOM elements and then activate the translator
_shouldWrapTranslations = true;
i18n.reRenderTranslations();
window.communityTranslator.load();
debug( 'Translator activated' );
return true;
}
activate 的关键动作是把 _shouldWrapTranslations 置为 true,然后调用 i18n.reRenderTranslations() 让所有已渲染的翻译文本重新走一遍翻译管道——此时 wrapTranslation() 会介入,为每个翻译文本包上 <data> 元素并写入 data-singular、data-context、data-plural 等标记(见 client/lib/translator-jumpstart/index.jsx)。
而 deactivate() 则相反:
function deactivate() {
window.communityTranslator.unload();
// Remove all the data tags from the DOM
_shouldWrapTranslations = false;
i18n.reRenderTranslations();
debug( 'Translator deactivated' );
return false;
}
3.2 激活后的首启引导弹窗
第一次激活时,如果用户之前没有勾选“Don't show again”,会弹出说明弹窗(renderConfirmationModal,见 launcher.jsx),提示:
“You have now enabled the translator. Right click the text to translate it.”
弹窗里有一个 FormInputCheckbox,勾选后会把 translator_hide_infodialog 写入 localStorage(toggleInfoCheckbox),此后不再打扰用户。同时首次激活还会上报 bumpStat( 'calypso_translator_toggle', 'intial_activation' ) 统计事件。
3.3 翻译更新如何回流到 i18n
社区翻译器脚本加载后注册的回调是 communityTranslatorJumpstart.updateTranslation(client/lib/translator-jumpstart/index.jsx)。当用户在页面里提交了一条翻译,外部脚本会把翻译对传回:
updateTranslation( newTranslation ) {
const locale = i18n.getLocale();
const key = newTranslation.key;
const plural = newTranslation.plural;
const translations = newTranslation.translations;
// jed expects:
// 'context\004singular': [plural, translatedSingular, translatedPlural...]
locale[ key ] = [ plural ].concat( translations );
i18n.setLocale( locale );
}
它把新翻译按 jed 期望的 context\004singular -> [plural, translated...] 格式合并进当前 locale,并调用 i18n.setLocale( locale ) 触发界面即时刷新——这就是“页面内翻译”即时生效的原理。
四、Deliverable:批量收集页面字符串并提交
TranslatorLauncher 还包含一个相对独立但非常实用的子功能:Deliverable(交付物)创建。它允许翻译者把页面上的一组相关字符串打包成一个“交付物”,跳转到 GlotPress 上批量提交翻译。
4.1 高亮模式与字符串收集
激活翻译器后,用户可以通过快捷键或点击启动器进入“高亮模式”。键盘快捷键的处理在 handleKeyDown(launcher.jsx):
handleKeyDown = ( event ) => {
const { isActive, selectedDeliverableTarget } = this.state;
if ( ! isActive || ! event.getModifierState( 'Control' ) || event.key.toLowerCase() !== 'd' ) {
return;
}
if ( selectedDeliverableTarget ) {
this.toggleSelectedDeliverableTarget();
}
this.toggleDeliverableHighlight();
};
即 Ctrl + D 切换高亮模式。开启高亮后,组件会监听 mousemove、mousedown、click、scroll 事件(toggleDeliverableHighlight,见 launcher.jsx),鼠标悬停到的元素会被套上一个高亮框:
const { left, top, width, height } = target.getBoundingClientRect();
const style = {
transform: `translate(${ left }px, ${ top + scrollTop }px)`,
width: `${ width }px`,
height: `${ height }px`,
};
return ReactDOM.createPortal(
<Fragment>
<div
ref={ this.highlightRef }
className="community-translator__highlight"
style={ style }
/>
{ this.renderDeliverableForm() }
</Fragment>,
document.body
);
高亮框通过 ReactDOM.createPortal 渲染到 document.body,避免被页面的 overflow 或 transform 影响定位。样式上(style.scss)它用一个 outline: 1000vw solid rgba(0, 0, 0, 0.5) 的巨型轮廓把页面其余部分压暗,形成聚光灯效果。
选中目标元素后,getOriginalIds(launcher.jsx)会从该元素及其子元素中扫描所有 translator-original-(\d+) 形式的 class,收集去重后的原始字符串 ID 列表。
4.2 创建 Deliverable 的 URL 与提交栏
选中目标后,页面底部会出现一个橙色提交栏(renderDeliverableForm,样式见 style.scss 的 community-translator__bar),显示“N strings found. Enter a title:”以及输入框和 “Create Deliverable” / “Cancel” 按钮。
提交时跳转的 URL 由 getCreateDeliverableUrl 构造(launcher.jsx):
getCreateDeliverableUrl = () => {
const DELIVERABLES_ENDPOINT = 'https://translate.wordpress.com/deliverables/create';
const { deliverableTitle } = this.state;
return addQueryArgs( DELIVERABLES_ENDPOINT, {
original_ids: this.getOriginalIds().join( ',' ),
title: deliverableTitle,
} );
};
即把收集到的 original_ids(逗号分隔)与标题拼到 https://translate.wordpress.com/deliverables/create 上,用新窗口打开。
4.3 选中期间的语言切换细节
选中 Deliverable 目标时,组件会临时把界面语言切回英语(setLocale( 'en' )),便于翻译者查看原始英文文案;取消选择后再恢复用户原本的语言(见 toggleSelectedDeliverableTarget,launcher.jsx):
const DEFAULT_LANGUAGE = 'en';
setLocale( DEFAULT_LANGUAGE );
// ...取消时
this.selectedLanguageSlug && this.props.setLocale( this.selectedLanguageSlug );
同时,has-deliverable-highlighted 这个 body class 会关闭翻译标记的 text-shadow 高亮,并隐藏通知条、环境角标和翻译器启动器本身,避免干扰(见 style.scss)。
五、GlotPress 环境适配与调试
5.1 与哪个 GlotPress 实例通信
社区翻译器所需的 GlotPress 连接参数定义在 client/lib/translator-jumpstart/index.jsx:
const translationDataFromPage = {
localeCode: 'en',
languageName: 'English',
pluralForms: 'nplurals=2; plural=(n != 1)',
contentChangedCallback() {},
glotPress: {
url: 'https://translate.wordpress.com',
project: 'wpcom',
translation_set_slug: 'default',
},
};
glotPress.project 默认是 wpcom,对应 https://translate.wordpress.com/projects/wpcom/。这些数据被挂在 window.translatorJumpstart 全局对象上,供外部注入的社区翻译器脚本读取。
对于没有官方翻译集的语言变体(如 de_formal),updateTranslationData 会通过 translateSetSlugs 映射到正确的翻译集 slug(client/lib/translator-jumpstart/index.jsx):
const translateSetSlugs = {
de_formal: 'formal',
};
// ...
translationDataFromPage.glotPress.translation_set_slug = translateSetSlugs[ localeVariant ] || 'default';
另外,翻译器的“等待审核中的翻译”加载功能还支持通过 URL 参数指定项目与翻译集:?load-user-translations=username&project=test&translationSet=formal&locale=de(详见 client/lib/i18n-utils/README.md),方便翻译审校者在非生产环境用 test 项目做验证。
5.2 开启调试日志
translator-jumpstart 模块自带 debug 日志,命名空间为 calypso:community-translator。在浏览器控制台执行以下命令即可打开:
localStorage.setItem( 'debug', 'calypso:community-translator' );
如果想同时看到界面实际展示的翻译字符串信息(来自 calypso:i18n),可以合并命名空间:
localStorage.setItem( 'debug', 'calypso:i18n,calypso:community-translator' );
设置后刷新页面,控制台便会输出模块初始化、脚本加载、翻译包裹与激活/停用等各环节的调试信息。
六、两个辅助功能:Translation Scanner 与 Empathy Mode
启动器源码中还有两个与社区翻译配套的功能标志位,分别受 config.isEnabled( 'i18n/translation-scanner' ) 和 config.isEnabled( 'i18n/empathy-mode' ) 控制(见 launcher.jsx)。
6.1 Translation Scanner:自动上报未收录的原文
TranslationScanner 定义在 client/lib/i18n-utils/translation-scanner.js,它通过 registerTranslateHook 监听所有经过 i18n 管道的翻译,把页面上出现的尚未被 GlotPress 收录的原文自动上报:
translationFilter( ...args ) {
const [ translation, options ] = args;
if ( this.active && this.sessionId ) {
this.recordOriginal( options.original, options.context || '' );
}
return translation;
}
其激活时机与 GlotPress 会话相关:它每秒钟轮询一次 cookie(cookieWatcherInterval),一旦发现 gp-record cookie 中出现了新的会话 ID(即用户登录了 translate.wordpress.com 并进入收录模式),就启动扫描(见 translation-scanner.js)。收集到的原文键(格式为 context\u0004original,见 client/lib/i18n-utils/glotpress.js)以 500ms 防抖批量 POST 到 https://translate.wordpress.com/api/translations/-record-originals(glotpress.js)。
该功能在 config/development.json、config/horizon.json、config/production.json 和 config/wpcalypso.json 中默认开启,主要用于帮助翻译团队发现“漏网”的字符串。
6.2 Empathy Mode:模拟不识字用户的真实感受
Empathy Mode(共情模式)定义在 client/lib/i18n-utils/empathy-mode.js,它的作用是把界面中未翻译的英文文案替换为重复的占位符(默认占位符是翻译后的 “I don't understand”),让翻译审校者亲身体验非英语用户在缺少翻译时的真实感受:
if ( i18n.hasTranslation( options ) ) {
return i18nEmpathyTranslate( options );
}
return '👉 ' + encodeUntranslatedString( options.original );
encodeUntranslatedString 会用占位符字符串反复拼接、截断到与原文等长,保证视觉上“有内容但看不懂”。当用户开启 Empathy Mode 后,前面提到过:启动器按钮会临时变成 Empathy Mode 的开关(见 launcher.jsx),且按钮上会出现当前语言代码的徽标(community-translator__badge),并显示 “Activate/Deactivate Empathy mode” 字样。
这个功能只在 config/development.json 与 config/stage.json 中开启,生产环境(config/production.json)为关闭状态。
七、配置项速查与适用环境
将上述功能涉及的配置项汇总如下,便于开发者快速核对:
| 配置项 | 作用 | 启用环境(以仓库现有配置为准) |
|---|---|---|
restricted_me_access |
控制 CommunityTranslatorMain 入口是否渲染启动器 |
由各环境 me 相关配置决定 |
i18n/translation-scanner |
开启 Translation Scanner,自动上报未收录原文 | development / horizon / production / wpcalypso |
i18n/empathy-mode |
开启 Empathy Mode(占位符替换未翻译文案) | development / stage(production 关闭) |
各配置项的实际值可在 config/development.json、config/horizon.json、config/production.json、config/stage.json、config/wpcalypso.json 中逐一核对。
八、小结
Community Translator 组件是 Calypso 社区本地化流程的重要一环:它通过 launcher.jsx 提供的常驻按钮,把“页面内翻译”能力封装成一个对普通用户完全隐藏、对翻译贡献者一键可达的工具;底层由 client/lib/translator-jumpstart/index.jsx 完成外部脚本注入、data-* 标记包裹与翻译回写;并通过 Translation Scanner 与 GlotPress 保持原文收录的闭环,配合 Empathy Mode 帮助审校者评估翻译缺失的体验影响。理解这套组件的挂载、状态机与配置开关,即可在 Calypso 相关环境中复现、调试或扩展社区翻译能力。