README

通过 DeeplApi 为 Neos 提供自动翻译

一旦编辑选择在另一种语言中“创建并复制”版本，文档和内容将自动翻译。包含的 DeeplService 也可以用于其他目的。

该开发是 Sitegeist 和 Code Q 的合作成果。

作者和赞助商

• Martin Ficzel - ficzel@sitegeist.de
• Felix Gradinaru - fg@codeq.at

本软件包的开发和公开发布得到了我们雇主 http://www.sitegeist.de 和 http://www.codeq.at 的慷慨赞助。

安装

Sitegeist.LostInTranslation 通过 packagist 提供。运行 composer require sitegeist/lostintranslation。

我们使用语义版本控制，因此每次重大更改都会增加主版本号。

工作原理

默认情况下，所有内联可编辑属性都使用 DeepL 进行翻译（参见设置 translateInlineEditables）。要将其他 string 属性包含在自动翻译中，可以在属性配置中使用 options.automaticTranslation: true。此外，您可以通过设置 options.automaticTranslation: false 来禁用某些节点类型的自动翻译。

一些非常常见的来自 Neos.Neos:Document 的字段默认已经配置为这样做。

'Neos.Neos:Document':
  options:
      automaticTranslation: true
  properties:
    title:
      options:
        automaticTranslation: true
    titleOverride:
      options:
        automaticTranslation: true
    metaDescription:
      options:
        automaticTranslation: true
    metaKeywords:
      options:
        automaticTranslation: true

此外，默认情况下已启用从 Neos.Neos:Node 继承的所有类型的自动翻译。

'Neos.Neos:Node':
  options:
      automaticTranslation: true

配置

此软件包需要从 https://www.deepl.com/pro-api 获取 DeeplL Api 的认证密钥。有一些免费计划支持有限数量的用户，但为了生产性使用，我们建议使用付费计划。

Sitegeist:
  LostInTranslation:
    DeepLApi:
      authenticationKey: '.........................'

通过设置配置节点可以配置节点的翻译。

Sitegeist:
  LostInTranslation:
    nodeTranslation:
      #
      # Enable the automatic translations of nodes while they are adopted to another dimension
      #
      enabled: true

      #
      # Translate all inline editable fields without further configuration.
      #
      # If this is disabled iline editables can be configured for translation by setting
      # `options.translateOnAdoption: true` for each property seperatly
      #
      translateInlineEditables: true

      #
      # The name of the language dimension. Usually needs no modification
      #
      languageDimensionName: 'language'

要为语言预置启用自动化翻译，将 options.translationStrategy 设置为 once、sync 或 none。默认模式是 once；

• once 会在编辑器切换到后端编辑此节点时的语言时仅翻译一次节点。如果您想获取初始翻译但之后自己处理不同变体，这很有用。
• sync 会在默认语言的节点发布时翻译并同步节点。因此，使用此选项在自动翻译的语言中使用节点变体进行编辑将没有意义，因为您的更改每次都会被覆盖。
• none 不会为此维度翻译变体。

如果语言维度的预置使用与 DeepL 不兼容的本地标识符，可以通过 options.deeplLanguage 显式配置此预置的 DeeplLanguage。

Neos:
  ContentRepository:
    contentDimensions:
      'language':

        #
        # The `defaultPreset` marks the source of for all translations whith mode `sync`
        #
        label: 'Language'
        default: 'en'
        defaultPreset: 'en'

        presets:

          #
          # English is the main language of the editors and spoken by editors,
          # the automatic translation is disabled therefore
          #
          'en':
            label: 'English'
            values: ['en']
            uriSegment: 'en'
            options:
              translationStrategy: 'none'

          #
          # Danish uses a different locale identifier then DeepL so the `deeplLanguage` has to be configured explicitly
          # Here we use the "once" strategy, which will translate nodes only once on switching the language
          #
          'dk':
            label: 'Dansk'
            values: ['dk']
            uriSegment: 'dk'
            options:
              deeplLanguage: 'da'
              translationStrategy: 'once'

          #
          # For German, we want to have a steady sync of nodes
          #
          'de':
            label: 'Bayrisch'
            values: ['de']
            uriSegment: 'de'
            options:
              translationStrategy: 'sync'

          #
          # The bavarian language is not supported by DeepL and is disabled
          #
          'de_bar':
            label: 'Bayrisch'
            values: ['de_bar','de']
            uriSegment: 'de_bar'
            options:
              translationStrategy: 'none'

忽略术语

您可以在配置中定义 DeepL 应忽略的术语。搜索时，术语将不区分大小写进行评估，但它们总是用它们的实际出现替换。

以下是一个示例配置可能的样子

Sitegeist:
  LostInTranslation:
    DeepLApi:
      ignoredTerms:
        - 'Sitegeist'
        - 'Neos.io'
        - 'Hamburg'

Eel Helper

该软件包还提供了两个 Eel Helper 来在 Fusion 中翻译文本。

⚠️ 这些电鳗助手中的每一个都会向DeepL发出单独的请求。因此，在一个页面上有太多这样的助手可能会显著降低页面未缓存的性能。:bulb: 仅当翻译缓存启用时使用！

要翻译单个文本，可以使用

# ${Sitegeist.LostInTranslation.translate(string textToBeTranslated, string targetLanguage, string|null sourceLanguage = null): string}
${Sitegeist.LostInTranslation.translate('Hello world!', 'de', 'en')}
# Output: Hallo Welt!

要翻译文本数组，可以使用

# ${Sitegeist.LostInTranslation.translate(array textsToBeTranslated, string targetLanguage, string|null sourceLanguage = null): array}
${Sitegeist.LostInTranslation.translate(['Hello world!', 'My name is...'], 'de', 'en')}
# Output: ['Hallo Welt!', 'Mein Name ist...']

比较并更新翻译

丢失在翻译中的包包含两个原型，用于可视化当前翻译和默认翻译之间的差异。

要在后端显示信息，可以在ContentCollection附近渲染Sitegeist.LostInTranslation:Collection.TranslationInformation。

content = Neos.Fusion:Join {
     info = Sitegeist.LostInTranslation:Collection.TranslationInformation {
          nodePath = 'content'
     }
     content = Neos.Neos:ContentCollection {
          nodePath = 'content'
     }
}

Sitegeist.LostInTranslation:Document.TranslationInformation

在文档级别显示有关缺失和过时翻译的信息。允许“翻译缺失”和“更新过时”节点。原型仅在后端+编辑模式下显示。

• node：(Node，默认为来自融合上下文的documentNode）要比较的文档节点
• referenceLanguage：(字符串，默认为语言预设）用于比较的预设

Sitegeist.LostInTranslation:Collection.TranslationInformation

在内容集合级别显示有关缺失和过时翻译的信息。允许“翻译缺失”和“更新过时”节点。原型仅在后端+编辑模式下显示。

• nodePath：(字符串，默认为null）
• node：(Node，默认为来自融合上下文的node）
• referenceLanguage：(字符串，默认为语言预设）用于比较的预设

翻译缓存

该插件包括用于DeepL API的翻译缓存，可存储单个文本部分及其翻译结果长达一周。默认情况下，缓存已启用。要禁用缓存，您需要设置以下设置

Sitegeist:
  LostInTranslation:
    DeepLApi:
      enableCache: false

性能

对于每个翻译节点，都会向DeepL API发出单个请求。当大量节点的文档被翻译时，这可能导致显著的延迟。预计未来版本将改进这一点。

贡献

我们乐意接受贡献。请发送给我们拉取请求。

更改日志

2.0.0

• 引入了预设选项translationStrategy。现在有两种自动翻译策略
  • 策略once将节点在“采用”时自动翻译一次，即编辑器切换到不同的语言维度
  • 策略sync将在默认预设语言中更新节点时自动翻译并同步节点
• 节点设置options.translateOnAdoption已重命名为options.automaticTranslation
• 引入了新的节点选项options.automaticTranslation