ckeditor5/locale：国际化方案

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ń'])，会根据id ADD_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\_@ckeditor_ckeditor5-heading@16.0.0@@ckeditor\ckeditor5-heading\lang\translations\zh-cn.po
    const pathToPoFile = pathToTranslationDirectory + path.sep + this._language + '.po';
    this._loadPoFile( pathToPoFile );
}

如上代码，会输出各ckeditor包中指定目录下指定语言的po文件，如node_modules\_@ckeditor_ckeditor5-heading@16.0.0@@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”的效果。