尧图网站建设 
Wagtail v3 API 中的 Locales 管理与翻译工作流从 CRUD 到多语言内容驱动【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailWagtail 8.0 引入的 v3 API基于 Django Ninja 与类型注解构建详见 v3 API 总览将语言环境Locale管理能力完整开放给开发者/api/v3/locales/提供面向认证请求的 Locale CRUD支持多语言站点的远程创建、查询、修改与删除。本文将围绕官方文档 locales.md 展开结合仓库源码深入讲解 Locales 端点的请求/响应结构、校验与删除保护机制、权限模型以及页面与 Snippet 上的翻译工作流支持帮助你通过 API 驱动多语言 CMS 的内容管理。Locales 端点总览认证与可用性前提语言环境Locale在 Wagtail 中代表站点内容的一种语言版本。v3 API 将其暴露在/api/v3/locales/且仅对认证请求开放不提供匿名访问——这一点与 pages、images 等允许匿名访问的公共端点不同。即使只是列表或详情查询也必须携带有效的 Bearer Token。认证方式遵循 v3 API 认证文档在每个请求头中携带Authorization: Bearer wagtail_…Token 绑定到用户账号其权限与在管理员后台执行操作一致。Token 可以在后台Settings → API tokens创建也可以用命令行生成./manage.py api_tokens create --userdeploy --namedeploy bot使用 Locales 端点前还需满足两个前提在INSTALLED_APPS中加入wagtail.api.v3并在urls.py中挂载wagtail.api.v3.urls.api建议挂载在/api/v3-preview/详见 快速开始Locales 端点仅在对应的 Wagtail 应用已安装且模型已注册时才会出现在 API 中——按 index.md 的说明images、documents、snippets、locales、redirects 端点都遵循这一规则。CRUD 操作与响应结构Locales 以标准 CRUD 形式暴露端点路径与 HTTP 方法如下操作方法与路径说明列表GET /locales/列出语言环境分页返回详情GET /locales/{locale_id}/返回单个语言环境创建POST /locales/创建语言环境更新PUT /locales/{locale_id}/更新语言环境删除DELETE /locales/{locale_id}/删除语言环境一个语言环境的响应包含五个字段这在 router.py 的LocaleSchema中有精确定义字段类型含义id正整数语言环境主键language_code字符串语言代码如fr、endisplay_name字符串语言的展示名称由Locale实例的字符串表示解析见resolve_display_nameis_bidi布尔是否为双向文本语言如阿拉伯语、希伯来语is_default布尔是否为默认语言环境请求输入则只有一个字段language_code。官方文档给出的创建示例curl -X POST https://example.com/api/v3/locales/ \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {language_code: fr}从源码看创建端点router.py将请求体交给LocaleForm校验再通过动作注册表action_registry中的create动作执行持久化成功后返回201及新建语言环境的完整LocaleSchema。更新端点router.py则使用LocaleForm(data, instancelocale)走edit动作成功后返回更新后的对象。列表分页与 v3 API 其他列表端点一致GET /locales/使用 limit/offset 分页响应形如{ count: 42, items: [] }count是不受分页影响的总结果数通过?limit与?offset翻页WAGTAILAPI_LIMIT_MAX设置会限制limit的最大取值参见 API 设置参考。输入校验语言代码的合法性与唯一性创建和更新时的校验由LocaleFormforms.py承担它继承 DjangoModelForm核心逻辑包括语言代码必须是受支持的语言language_code字段是一个ChoiceField其可选值来自get_content_languages().items()。该函数coreutils.py优先读取 Django 设置WAGTAIL_CONTENT_LANGUAGES若未配置则回退为基于LANGUAGE_CODE推导的单一语言。也就是说POST {language_code: fr}只有在fr属于站点配置的内容语言时才能通过校验否则返回校验错误。语言代码不能重复表单构造时会读取Locale.objects中已使用的语言代码并从可选列表中剔除因此重复的语言代码会被拒绝。更新时的边界处理如果实例当前的language_code已不在受支持列表中language_code_is_valid()为假表单会插入一个空选项Select a new language避免 Django 自动选中一个随机语言。删除保护两道防线删除端点router.py通过_check_can_delete施加两道保护router.py不能删除最后一个语言环境若Locale.all_objects.exclude(pklocale.pk).exists()为假即系统中只剩这一个语言环境删除会被拒绝不能删除仍被使用的语言环境调用get_locale_usage(locale)utils.py统计引用该语言环境的页面数和其他可翻译对象数只要不是(0, 0)就拒绝删除。统计口径是页面按Page.objects.filter(localelocale).exclude(depth1)计数排除根节点其他对象遍历所有get_translatable_models()中的模型逐个累加。这两道防线确保通过 API 删除语言环境时不会破坏站点的翻译引用关系也不会让系统进入无语言环境的非法状态。权限模型每个操作要求的权限Locales 端点使用require_any_permission装饰器做权限门控权限策略来自policy_registry.get_by_type(Locale)。从 router.py 可以看到各操作的要求操作要求的权限GET /locales/、GET /locales/{id}/add/change/delete/view任一即可POST /locales/addPUT /locales/{id}/changeDELETE /locales/{id}/delete列表与详情还会进一步按用户的权限范围过滤instances_user_has_any_permission_for(request.user, (add, change, delete, view))保证用户只能看到自己拥有权限的语言环境集合。创建动作在执行时显式传入了skip_permission_checksTrue因为权限已在端点层完成校验而更新动作则交由edit动作执行。结合 认证文档 的说明Token 以 HMAC-SHA-256 摘要存储并绑定SECRET_KEY其权限等同于所绑定的用户账号。因此要为 API 客户端开放 Locales 管理应在Settings → Groups中为对应账号或专用服务账号授予 Locale 的相应权限。翻译工作流支持不止是管理语言环境本身除了语言环境本身的 CRUDv3 API 还支持通过 API 完成翻译工作流页面Pages页面端点支持locale与translation_of两个过滤器详见 pages.mdlocale仅返回指定语言环境的页面translation_of仅返回指定页面的翻译版本且源页面本身会被排除。页面提供copy_for_translation动作路径为/pages/{page_id}/actions/copy_for_translation/pages.md。它要求启用 i18n并需要翻译提交translation submit权限。请求体支持的参数参数说明locale目标语言代码例如fr必填copy_parents同时复制页面的祖先页面alias以别名alias而非完整副本形式创建recursive包含页面的子树示例请求体{locale: fr, recursive: true}。调用成功后返回201及新翻译页面的详情。Snippet代码片段对于基于TranslatableMixin模型的 Snippet端点同样支持locale、translation_of过滤器以及copy_for_translation动作详见 snippets.md将翻译能力从页面延伸到可翻译的 Snippet 模型。需要说明的是持续的翻译同步ongoing translation synchronization与wagtail-localize工作流目前尚未通过 v3 API 开放copy_for_translation只负责创建初始翻译副本。错误处理约定与其他 v3 API 端点一致Locales 端点的校验失败遵循 RFC 7807 的application/problemjson错误格式HTTP 422认证失败返回401、权限不足返回403未找到资源返回404。示例{ type: about:blank, title: Unprocessable Entity, status: 422, detail: Validation failed, errors: [] }参考资源端点实现源码wagtail/locales/api/v3/router.py输入校验表单wagtail/locales/forms.py语言使用统计工具wagtail/locales/utils.py内容语言来源函数wagtail/coreutils.py相关文档v3 API 总览、认证机制、页面端点、Snippet 端点官方 OpenAPI 快照中包含每个 Locale 端点的完整生成式参考参见 API 参考【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Wagtail v3 API 中的 Locales 管理与翻译工作流：从 CRUD 到多语言内容驱动
Wagtail v3 API 中的 Locales 管理与翻译工作流从 CRUD 到多语言内容驱动【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailWagtail 8.0 引入的 v3 API基于 Django Ninja 与类型注解构建详见 v3 API 总览将语言环境Locale管理能力完整开放给开发者/api/v3/locales/提供面向认证请求的 Locale CRUD支持多语言站点的远程创建、查询、修改与删除。本文将围绕官方文档 locales.md 展开结合仓库源码深入讲解 Locales 端点的请求/响应结构、校验与删除保护机制、权限模型以及页面与 Snippet 上的翻译工作流支持帮助你通过 API 驱动多语言 CMS 的内容管理。Locales 端点总览认证与可用性前提语言环境Locale在 Wagtail 中代表站点内容的一种语言版本。v3 API 将其暴露在/api/v3/locales/且仅对认证请求开放不提供匿名访问——这一点与 pages、images 等允许匿名访问的公共端点不同。即使只是列表或详情查询也必须携带有效的 Bearer Token。认证方式遵循 v3 API 认证文档在每个请求头中携带Authorization: Bearer wagtail_…Token 绑定到用户账号其权限与在管理员后台执行操作一致。Token 可以在后台Settings → API tokens创建也可以用命令行生成./manage.py api_tokens create --userdeploy --namedeploy bot使用 Locales 端点前还需满足两个前提在INSTALLED_APPS中加入wagtail.api.v3并在urls.py中挂载wagtail.api.v3.urls.api建议挂载在/api/v3-preview/详见 快速开始Locales 端点仅在对应的 Wagtail 应用已安装且模型已注册时才会出现在 API 中——按 index.md 的说明images、documents、snippets、locales、redirects 端点都遵循这一规则。CRUD 操作与响应结构Locales 以标准 CRUD 形式暴露端点路径与 HTTP 方法如下操作方法与路径说明列表GET /locales/列出语言环境分页返回详情GET /locales/{locale_id}/返回单个语言环境创建POST /locales/创建语言环境更新PUT /locales/{locale_id}/更新语言环境删除DELETE /locales/{locale_id}/删除语言环境一个语言环境的响应包含五个字段这在 router.py 的LocaleSchema中有精确定义字段类型含义id正整数语言环境主键language_code字符串语言代码如fr、endisplay_name字符串语言的展示名称由Locale实例的字符串表示解析见resolve_display_nameis_bidi布尔是否为双向文本语言如阿拉伯语、希伯来语is_default布尔是否为默认语言环境请求输入则只有一个字段language_code。官方文档给出的创建示例curl -X POST https://example.com/api/v3/locales/ \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {language_code: fr}从源码看创建端点router.py将请求体交给LocaleForm校验再通过动作注册表action_registry中的create动作执行持久化成功后返回201及新建语言环境的完整LocaleSchema。更新端点router.py则使用LocaleForm(data, instancelocale)走edit动作成功后返回更新后的对象。列表分页与 v3 API 其他列表端点一致GET /locales/使用 limit/offset 分页响应形如{ count: 42, items: [] }count是不受分页影响的总结果数通过?limit与?offset翻页WAGTAILAPI_LIMIT_MAX设置会限制limit的最大取值参见 API 设置参考。输入校验语言代码的合法性与唯一性创建和更新时的校验由LocaleFormforms.py承担它继承 DjangoModelForm核心逻辑包括语言代码必须是受支持的语言language_code字段是一个ChoiceField其可选值来自get_content_languages().items()。该函数coreutils.py优先读取 Django 设置WAGTAIL_CONTENT_LANGUAGES若未配置则回退为基于LANGUAGE_CODE推导的单一语言。也就是说POST {language_code: fr}只有在fr属于站点配置的内容语言时才能通过校验否则返回校验错误。语言代码不能重复表单构造时会读取Locale.objects中已使用的语言代码并从可选列表中剔除因此重复的语言代码会被拒绝。更新时的边界处理如果实例当前的language_code已不在受支持列表中language_code_is_valid()为假表单会插入一个空选项Select a new language避免 Django 自动选中一个随机语言。删除保护两道防线删除端点router.py通过_check_can_delete施加两道保护router.py不能删除最后一个语言环境若Locale.all_objects.exclude(pklocale.pk).exists()为假即系统中只剩这一个语言环境删除会被拒绝不能删除仍被使用的语言环境调用get_locale_usage(locale)utils.py统计引用该语言环境的页面数和其他可翻译对象数只要不是(0, 0)就拒绝删除。统计口径是页面按Page.objects.filter(localelocale).exclude(depth1)计数排除根节点其他对象遍历所有get_translatable_models()中的模型逐个累加。这两道防线确保通过 API 删除语言环境时不会破坏站点的翻译引用关系也不会让系统进入无语言环境的非法状态。权限模型每个操作要求的权限Locales 端点使用require_any_permission装饰器做权限门控权限策略来自policy_registry.get_by_type(Locale)。从 router.py 可以看到各操作的要求操作要求的权限GET /locales/、GET /locales/{id}/add/change/delete/view任一即可POST /locales/addPUT /locales/{id}/changeDELETE /locales/{id}/delete列表与详情还会进一步按用户的权限范围过滤instances_user_has_any_permission_for(request.user, (add, change, delete, view))保证用户只能看到自己拥有权限的语言环境集合。创建动作在执行时显式传入了skip_permission_checksTrue因为权限已在端点层完成校验而更新动作则交由edit动作执行。结合 认证文档 的说明Token 以 HMAC-SHA-256 摘要存储并绑定SECRET_KEY其权限等同于所绑定的用户账号。因此要为 API 客户端开放 Locales 管理应在Settings → Groups中为对应账号或专用服务账号授予 Locale 的相应权限。翻译工作流支持不止是管理语言环境本身除了语言环境本身的 CRUDv3 API 还支持通过 API 完成翻译工作流页面Pages页面端点支持locale与translation_of两个过滤器详见 pages.mdlocale仅返回指定语言环境的页面translation_of仅返回指定页面的翻译版本且源页面本身会被排除。页面提供copy_for_translation动作路径为/pages/{page_id}/actions/copy_for_translation/pages.md。它要求启用 i18n并需要翻译提交translation submit权限。请求体支持的参数参数说明locale目标语言代码例如fr必填copy_parents同时复制页面的祖先页面alias以别名alias而非完整副本形式创建recursive包含页面的子树示例请求体{locale: fr, recursive: true}。调用成功后返回201及新翻译页面的详情。Snippet代码片段对于基于TranslatableMixin模型的 Snippet端点同样支持locale、translation_of过滤器以及copy_for_translation动作详见 snippets.md将翻译能力从页面延伸到可翻译的 Snippet 模型。需要说明的是持续的翻译同步ongoing translation synchronization与wagtail-localize工作流目前尚未通过 v3 API 开放copy_for_translation只负责创建初始翻译副本。错误处理约定与其他 v3 API 端点一致Locales 端点的校验失败遵循 RFC 7807 的application/problemjson错误格式HTTP 422认证失败返回401、权限不足返回403未找到资源返回404。示例{ type: about:blank, title: Unprocessable Entity, status: 422, detail: Validation failed, errors: [] }参考资源端点实现源码wagtail/locales/api/v3/router.py输入校验表单wagtail/locales/forms.py语言使用统计工具wagtail/locales/utils.py内容语言来源函数wagtail/coreutils.py相关文档v3 API 总览、认证机制、页面端点、Snippet 端点官方 OpenAPI 快照中包含每个 Locale 端点的完整生成式参考参见 API 参考【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考