README

Neos包，便于处理CSV文件中的翻译标签，具有后端模块用于标签覆盖和命令行支持

此包允许直接在融合组件文件夹中以CSS模块风格轻松访问csv文件来管理翻译

该包包含一个后端模块用于覆盖翻译，以及命令行命令将覆盖返回到csv文件进行版本控制

优点

• 翻译直接在融合组件文件夹的*translation.csv文件中管理
• 翻译可以非常简单地进行添加和使用
• 可以直接在电子表格应用程序中编辑翻译，以直接查找缺失的翻译
• 可以通过后端模块由客户和管理员进行翻译更改
• 通过命令行将更改后的翻译存储回翻译文件
• Neos区域设置回退链和格式化程序的使用方式与经典xliff翻译相同

缺点

• 不支持（尚不支持）复数形式
• 由于文件会变得难以管理，因此此解决方案可能不适合真正大量的区域设置（>10）
• 不支持NodeType检查器标签的翻译

作者与赞助商

• Martin Ficzel - ficzel@sitegeist.de

此包的开发和公共发布得到了我们的雇主http://www.sitegeist.de的慷慨赞助。

用法

CsvPO助手提供了eel函数CsvPO.create，它接受翻译csv文件的路径作为参数。返回的对象允许在融合和afx中访问翻译。

示例.fusion

prototype(Vendor.Site:Example) < prototype(Neos.Fusion:Component) {

    @private.i18n = ${CsvPO.create('resource://Vendor.Site/Private/Fusion/Presentation/Example.translation.csv')}

    renderer = afx`
        <div>
            {private.i18n.title} <br/>
            {private.i18n["subtitle"]} <br/>
            {private.i18n.text({info:'foo'})}<br/>
            {private.i18n.missing}s
        </div>
    `
}

链式翻译和可选覆盖

当提供多个csv文件时，链中末尾文件的标签具有优先权。

prototype(Vendor.Site:Example) < prototype(Neos.Fusion:Component) {
    i18n = ${CsvPO.create('resource://Vendor.Site/Private/Fusion/TranslationChainExample/Generic.translation.csv', 'resource://Vendor.Site/Private/Fusion/TranslationChainExample/Override.translation.csv')}
}

结合Neos 8.3中融合的@private语法，这允许指定通用翻译，并允许传递具有优先权的翻译文件。

prototype(Vendor.Package:TranslationChainExample) < prototype(Neos.Fusion:Component) {

    # can be set from outside and is recommended to be null by default
    i18nOverride = 'resource://Vendor.Package/Private/Fusion/TranslationChainExample/Override.translation.csv'

    # combines a predefined translation with one that os passed as props.
    @private {
        i18n = ${CsvPO.create('resource://Vendor.Package/Private/Fusion/TranslationChainExample/Generic.translation.csv', props.i18nOverride)}
    }

    renderer = afx`
        <!-- access single translation -->
        <div>{private.i18n.example}</div>

        <!-- export all translations as json -->
        <div data-translations={Json.stringify(private.i18n.jsonSerialize())}></div>
    `
}

占位符

CSVPO支持与Flow的经典xliff翻译相同的占位符语法。见：https://flowframework.readthedocs.io/en/stable/TheDefinitiveGuide/PartIII/Internationalization.html?highlight=translations#placeholders

    # customize translation with params
    example1 = ${private.i18n.example('hello', 'world')}
    
    # placeholders can also be passed as array 
    example2 = ${private.i18n.example(['hello', 'world'])}
    
    # or as named data-structure
    example3 = ${private.i18n.example({title:"hello"})}

全局翻译

全局翻译可以提取到原型中，以在整个项目中使用。建议使用Neos.Fusion:Memo作为基本原型，以仅评估原型一次。

prototype(Vendor.Site:GlobalTranslations) < prototype(Neos.Fusion:Memo) {
    discriminator = 'Vendor.Site:GlobalTranslations'
    value = ${CsvPO.create('resource://Vendor.Site/Private/Fusion/Presentation/Globals.translation.csv')}
}

prototype(Vendor.Site:Example) < prototype(Neos.Fusion:Component) {

    @private.i18n = Vendor.Site:GlobalTranslations

    renderer = afx`
        <div>
            {private.i18n.title} <br/>
            {private.i18n.text({info:'foo'})}<br/>
        </div>
    `
}

在Development上下文中，如果标识符未知，则使用-- i18n-add --标记缺失的翻译，如果翻译值是空的，则使用-- i18n-translate --。在Production上下文中，如果没有确定翻译，则返回标识符。

CSV文件

每个csv文件管理所有区域设置中的多个翻译。csv的第一行被视为标题，用于标识翻译的含义。

示例.translation.csv

id,description,en,de
title,the title for the dialog,title,Titel
description,short explanation,text with {info} placeholder,Text mit {info} Platzhalter

规则

• 列id代表标签标识符
• 列 description 表示标签描述
• 所有其他列都被视为从标题行翻译成特定语言的版本
• 传递给翻译的参数将替换花括号中的占位符。
• 支持在翻译标签中使用 HTML 标记。
• CSV 文件使用 , 作为分隔符，使用 " 作为文本分隔符。

选择 CSV 文件是因为它具有广泛的工具支持，几乎所有电子表格应用都可以编辑这些文件。

注意：评估了使用 xliff 的方案，但已拒绝，因为它需要多个文件，使得查找缺失的翻译变得异常困难，并且工具支持非常薄弱。CSV 不支持的 xliff 功能只有很少使用的复数形式。

后端模块 & 策略

翻译后端模块允许显示给定源的所有翻译。可以定义翻译覆盖并可视化给编辑器以及回退。

后端模块对 Administrator 和 TranslationEditor 角色可用。编辑器 必须明确授予修改翻译的权限。

CLI

CvsPO 包含多个 CLI 命令

• csvpo:list 显示所有翻译源列表
• csvpo:show 显示指定源的翻译
• csvpo:showAll 显示指定源的翻译
• csvpo:bake 将指定源的翻译烘焙回 CSV 文件
• csvpo:bakeAll 将所有源的覆盖烘焙回 CSV 文件
• csvpo:reset 重置指定源的翻译覆盖
• csvpo:resetall 重置所有源的翻译覆盖

配置

以下配置允许控制包的行为和提供的管理选项。

Sitegeist:
  CsvPO:

    # render visible hint for missing translations
    # is enabled by default for debug mode
    debugMode: false

    # Control which translation options are available in
    # the backend module and the cli
    management:
      # enable locallization overrides, disables in contexts
      # without database like visual regression testing
      enabled: true    

      # package keys to scan for translation files
      packageKeys: []

      # list of locales to manage in the backend module
      locales: ['en']

      # file extension to search for translations
      fileExtension: '.translation.csv'

      # folder inside the package resources to search for translations
      resourcePath: 'Private/Fusion'

缓存

翻译被缓存在 Sitegeist_CsvPO_TranslationCache 缓存中。文件监视器将在任何 Flow-Package 的 Fusion 文件夹中的 .csv 文件更改时使缓存失效。

如果您在其他位置存储翻译 CSV 文件，确保在更改 translation.csv 后调用 ./flow cache:flushone Sitegeist_CsvPO_TranslationCache。

安装

Sitegeist.CsvPO 通过 packagist 提供。只需运行 composer require sitegeist/csvpo。我们使用语义版本控制，所以每次重大更改都会增加主版本号。