Wagtail Localize Smartling

Wagtail Localize的扩展，与Smartling翻译平台集成。

链接

• 文档
• 变更日志
• 贡献
• 安全
• Smartling API文档

支持版本

• Python 3.8+
• Django 4.2+
• Wagtail 6.1+

安装

1. 从PyPI安装软件包

   python -m pip install wagtail-localize-smartling
   

2. 将"wagtail_localize_smartling"添加到Django设置中的INSTALLED_APPS。确保它在"wagtail_localize"和"wagtail_localize.locales"之前

   INSTALLED_APPS = [
       ...
       "wagtail_localize_smartling",
       "wagtail_localize",
       "wagtail_localize.locales",
       ...
   ]
   

3. 在Django设置中配置插件

    WAGTAIL_LOCALIZE_SMARTLING = {
        # Required settings (get these from "Account settings" > "API" in the Smartling dashboard)
        "PROJECT_ID": "<project_id>",
        "USER_IDENTIFIER": "<user_identifier>",
        "USER_SECRET": "<user_secret>",
        # Optional settings and their default values
        "REQUIRED": False,  # Set this to True to always send translations to Smartling
        "ENVIRONMENT": "production",  # Set this to "staging" to use Smartling's staging API
        "API_TIMEOUT_SECONDS": 5.0,  # Timeout in seconds for requests to the Smartling API
    }
   

   如果你的项目的区域设置与Smartling中的设置不匹配（例如，你的项目中是ro，而在Smartling中是ro-RO），则可以通过LOCALE_TO_SMARTLING_LOCALE设置提供Wagtail区域ID到Smartling区域ID的映射

   WAGTAIL_LOCALIZE_SMARTLING = {
       "LOCALE_TO_SMARTLING_LOCALE": {
           "ro": "ro-RO"
       }
   }
   

   ...或者，你可以在LOCALE_MAPPING_CALLBACK设置中指定一个可调用的函数或指向该函数的点的路径

   def map_project_locale_to_smartling(locale: str) -> str:
       if locale == "ro":
           return "ro-RO"
       return locale
   
   
   WAGTAIL_LOCALIZE_SMARTLING = {
       # ...
       "LOCALE_MAPPING_CALLBACK": "settings.map_project_locale_to_smartling"
   }
   

   回调函数接收一个WAGTAIL_CONTENT_LANGUAGES本地代码字符串，并期望返回一个有效的映射区域ID（或原始区域ID）。

   请注意，默认情况下，在同步翻译时，项目将尝试将混合大小写的Smartling风格的语言代码（例如zh-CN）重新格式化为Django风格的全部小写代码（例如zh-cn）。根据你的项目中语言代码的设置，这种行为可能不合适。你可以通过将REFORMAT_LANGUAGE_CODES设置设置为False（默认为True）来禁用它。

   WAGTAIL_LOCALIZE_SMARTLING = {
       # ...
       "REFORMAT_LANGUAGE_CODES": False
   }
   

4. 运行迁移

   ./manage.py migrate
   

设置

Smartling项目设置

为了使插件与Smartling项目一起工作，Django/Wagtail国际化相关设置必须与项目的语言设置兼容。

• 只有与Smartling项目源语言相同的Wagtail内容才能进行翻译。
• 理想情况下，WAGTAIL_CONTENT_LANGUAGES中的语言标签应该是Smartling项目目标区域的完全匹配（不区分大小写）。例如，如果你的Smartling项目目标是fr-FR，那么你必须在WAGTAIL_CONTENT_LANGUAGES中包含"fr-fr"，而不仅仅是"fr"。但是，如果不可能实现这一点，请使用LOCALE_TO_SMARTLING_LOCALE或LOCALE_MAPPING_CALLBACK设置将你的Wagtail语言代码映射到Smartling语言代码。

同步

插件提供了一个名为sync_smartling的管理命令

• 为等待翻译的新内容在Smartling中创建作业
• 检查挂起的翻译作业的状态
• 下载并应用完成作业的翻译

此命令应通过cron或其他方式定期运行

./manage.py sync_smartling

我们建议每隔大约10分钟运行一次。

回调

除了sync_smartling管理命令外，插件还会将其创建的Smartling作业的callbackUrl字段设置为webhook处理器视图的URL。此处理器将主动下载并应用已完成作业的翻译，而不必等待下一次sync_smartling运行。此URL基于WAGTAILADMIN_BASE_URL设置，因此确保已设置并且可以从互联网访问非常重要。

[!WARNING] 不应将回调作为下载翻译的唯一方法。始终确保定期运行sync_smartling命令，以确保你的翻译是最新的。

用法

提交新内容进行翻译

更新翻译

它是如何工作的

工作流程

提交页面进行Smartling翻译

flowchart LR

    submitPageForTranslation["Page submitted for translation in Wagtail"]
    submitToSmartling{"
        User choses to submit
        translation job to Smartling?
    "}
    enterSmartlingJobConfig["User enters Smartling job config"]
    pendingSmartlingJobCreated["A pending Smartling job is created in Wagtail"]
    wagtailSyncedTranslationEditView["
        User is redirected to Wagtail's
        synced translation edit view
    "]

    submitPageForTranslation-->submitToSmartling
    submitToSmartling-->|Yes|enterSmartlingJobConfig
    enterSmartlingJobConfig-->pendingSmartlingJobCreated
    pendingSmartlingJobCreated-->wagtailSyncedTranslationEditView
    submitToSmartling-->|No|wagtailSyncedTranslationEditView

Smartling同步

django-admin sync_smartling，以下流程图描述了每个作业运行的逻辑

flowchart LR

    jobSentToSmartling{"Has the job been
    sent to Smartling yet?"}
    sendJobToSmartling["Send job to Smartling"]
    jobFinished{"Is the job finalised?"}
    updateJobFromSmartling["Update job from Smartling"]
    fin["End"]

    jobSentToSmartling-->|Yes|jobFinished
    jobSentToSmartling-->|No|sendJobToSmartling
    sendJobToSmartling-->fin
    jobFinished-->|Yes|fin
    jobFinished-->|No|updateJobFromSmartling

信号

此应用程序提供单个wagtail_localize.signals.translation_imported信号，当从Smartling导入翻译时发出。

信号kwargs

• sender：wagtail_localize_smartling.models.Job类
• instance：正在导入翻译的Job实例
• translation：正在导入翻译的wagtail_localize.models.Translation实例。使用translation.get_target_instance()获取翻译对应的模型实例（例如页面或片段）

发布新版本

1. 在https://github.com/mozilla/wagtail-localize-smartling/blob/main/src/wagtail_localize_smartling/__init__.py中提升版本
2. 更新CHANGELOG.md
3. 在主分支（通过PR，或者如果你确定这不会引起冲突，可以直接提交到main）提交和落地这些更改
4. 在main分支上标记发布为vX.Y.Z – 或者在第6步中通过GitHub UI创建标签。（如果你在本地创建了标签，记得使用git push --tags推送新的标签）
5. 通过https://github.com/mozilla/wagtail-localize-smartling/releases添加新的发布版本
6. 选择（或创建）新的标签，添加标题和描述
7. 确保新的发布版本被标记为最新版本（请查看发布描述下方的复选框）
8. 在GitHub内发布新的发布版本 - 自动化将处理其余部分并将它推送到PyPI