ckeditor5的locale方案会往全局变量window.CKEDITOR_TRANSLATIONS
上挂载映射用的字典信息:
window.CKEDITOR_TRANSLATIONS = {
pl: {
dictionary: {
'Cancel': 'Anuluj',
'Add space': [ 'Dodaj spację', 'Dodaj %0 spacje', 'Dodaj %0 spacji' ]
},
// A function that returns the plural form index.
getPluralForm: n => n !==1
}
add
方法会更新window.CKEDITOR_TRANSLATIONS
中对应语言下dictionary
和getPluralForm
方法:
locale = new Locale( {
uiLanguage: 'pl',
contentLanguage: 'de'
} );
const getPolishPluralForm = n => n == 1 ? 0 : n % 10 >= 2 && n % 10 <= 4 && ( n % 100 < 10 || n % 100 >= 20 ) ? 1 : 2;
add('pl', {
'foo': 'foo_pl',
'bar': [ 'bar_pl_0', '%0 bar_pl_1', '%0 bar_pl_2' ]
}, getPolishPluralForm);
addTranslations( 'de', {
'foo': 'foo_de',
'bar': [ 'bar_de_0', '%0 bar_de_1', '%0 bar_de_2' ]
} );
// 测试用例
const t = locale.t;
expect( t( { string: 'bar', plural: '%0 bars' }, [ 1 ] ), 1 ).to.equal( 'bar_pl_0' );
expect( t( { string: 'bar', plural: '%0 bars' }, [ 2 ] ), 2 ).to.equal( '2 bar_pl_1' );
expect( t( { string: 'bar', plural: '%0 bars' }, [ 5 ] ), 3 ).to.equal( '5 bar_pl_2' );
// 更新示例
add( 'pl', {
'ADD_SPACE': [ '%1 spację', '%1 %0 spacje', '%1 %0 spacji' ],
'Add': 'Dodaj',
'Remove': 'Usuń'
} );
const addOrRemoveSpaceMessage = { string: '%1 a space', plural: '%1 %0 spaces', id: 'ADD_SPACE' };
expect( t( addOrRemoveSpaceMessage, [ 1, t( 'Add' ) ] ), 1 ).to.equal( 'Dodaj spację' );
expect( t( addOrRemoveSpaceMessage, [ 2, t( 'Remove' ) ] ), 2 ).to.equal( 'Usuń 2 spacje' );
expect( t( addOrRemoveSpaceMessage, [ 5, t( 'Add' ) ] ), 3 ).to.equal( 'Dodaj 5 spacji' );
t(message, values = [])方法
- 如果
message
是字符串,那么将message
转换为对象形式message = { string: message}
如果values
不是数组,那么将values
转换为数组形式values = [ values]
- 如果存在
message.plural
,则常量quantity
取值values[0]
,否则quantity
设置为1 - 执行
translate(language, message, quantity)
方法到映射的值,可能直接就是原始的message
字符串,也可能是values中某个选项,而这个选项中可能有类似%o
、%1
这样的插值,这就需要执行下一步的interpolateString
方法再次转换。translate(language, message, quantity)
执行逻辑如下:
1.如果只有一种语言,也就是Object.keys( window.CKEDITOR_TRANSLATIONS ).length === 1
的话,将用这唯一的语言来设置入参language
2.如果window.CKEDITOR_TRANSLATIONS
中没有任何设置或者找不到messageId
(即message.id || message.string)对应的翻译,那么当入参quantity
为1
时,直接返回message.string
,不为1
时,直接返回message.plural
3.否则,当messageId
(即message.id || message.string)对应的翻译是字符串时,直接返回该字符串,例如上例中t( 'Add' )
返回的就是Dodaj
;如果对应的翻译是数组(用arr
临时表示),那么就要根据上例中add
方法的第三个入参即函数getPluralForm
和quantity
参数,来获取一个下标,然后返回arr[下标]
,例如上例中t( addOrRemoveSpaceMessage, [ 2, t( 'Remove' ) ] )
其实就是t({ string: '%1 a space', plural: '%1 %0 spaces', id: 'ADD_SPACE' }, [2, 'Usuń'])
,会根据idADD_SPACE
找到对应的翻译选项数组[ '%1 spację', '%1 %0 spacje', '%1 %0 spacji' ]
,然后通过getPolishPluralForm(2)
计算出下标为1,最终返回'%1 %0 spacje'
。 - 执行
interpolateString
,如上文(上一节第3小节)中示例最后返回'%1 %0 spacje'
,执行interpolateString('%1 %0 spacje', [2, 'Usuń'])
,结果为'Usuń 2 spacje'
。
// Fills the `%0, %1, ...` string placeholders with values.
function interpolateString( string, values ) {
return string.replace( /%(\d+)/g, ( match, index ) => {
return ( index < values.length ) ? values[ index ] : match;
} );
}
Setting the UI language
- 支持rtl语言,如阿拉伯语;
- 富文本UI语言默认是英语,支持npm、cdn和zip三种方式加载其他语言包;
- 也可以借助
ckeditor5-dev-webpack-plugin
插件,引用其他语言包,其原理大概是加载po
文件,将po
文件中的翻译纳入ckeditor中。大致步骤如下:
1.在po
文件中设置翻译用的映射信息
而zh-ch.po
文件中是一些翻译用的映射信息,截图如下:
图1:修改段落为段落123
图2:效果图
2.加载po
文件
loadPackage( pathToPackage ) {
if ( this._handledPackages.has( pathToPackage ) ) {
return;
}
this._handledPackages.add( pathToPackage );
const pathToTranslationDirectory = this._getPathToTranslationDirectory( pathToPackage, this._language );
// pathToPoFile即为po文件路径,如node_modules\_@[email protected]@@ckeditor\ckeditor5-heading\lang\translations\zh-cn.po
const pathToPoFile = pathToTranslationDirectory + path.sep + this._language + '.po';
this._loadPoFile( pathToPoFile );
}
如上代码,会输出各ckeditor包中指定目录下指定语言的po
文件,如node_modules\_@[email protected]@@ckeditor\ckeditor5-heading\lang\translations\zh-cn.po
图3:lang/translations/*.po
3.translateSource
方法(类似babel)通过acorn
修改源码,将调用t()
方法的地方,全部替换成翻译后的文本
function translateSource( source, sourceFile, translateString ) {
const comments = [];
const tokens = [];
const errors = [];
const ast = acorn.parse( source, {
sourceType: 'module',
ranges: true,
onComment: comments,
onToken: tokens,
ecmaVersion: 9
} );
let changesInCode = false;
walk.simple( ast, {
CallExpression: node => {
if ( node.callee.name !== 't' ) {
return;
}
if ( node.arguments[ 0 ].type !== 'Literal' ) {
errors.push( `First t() call argument should be a string literal in ${ sourceFile }.` );
return;
}
changesInCode = true;
node.arguments[ 0 ].value = translateString( node.arguments[ 0 ].value );
}
} );
// Optimization for files without t() calls.
if ( !changesInCode ) {
return { output: source, errors };
}
escodegen.attachComments( ast, comments, tokens );
const output = escodegen.generate( ast, {
comment: true
} );
return { output, errors };
};
效果举例:例如“图2:效果图”中标题下拉框,对应heading
插件,其依赖一个插件叫HeadingUI
,它的init
方法片段如下:
init() {
const dropdownTooltip = t( 'Heading' );
}
经过translateSource
代码转换后,代码转为:
init() {
const dropdownTooltip = t( '段落123' );
}
再例如,ckeditor5/src/utils中:
const localizedTitles = {
Paragraph: t( 'Paragraph' ),
'Heading 1': t( 'Heading 1' ),
'Heading 2': t( 'Heading 2' ),
'Heading 3': t( 'Heading 3' ),
'Heading 4': t( 'Heading 4' ),
'Heading 5': t( 'Heading 5' ),
'Heading 6': t( 'Heading 6' )
};
会转换为:
const localizedTitles = {
Paragraph: t('段落123'),
'Heading 1': t('标题 1'),
'Heading 2': t('标题 2'),
'Heading 3': t('标题 3'),
'Heading 4': t('标题 4'),
'Heading 5': t('标题 5'),
'Heading 6': t('标题 6')
};
通过上述方法,实现了“图2:效果图”中标题下拉框中的“段落123”的效果。