什么是原生内容集成?

当我们允许客户从保存被翻译内容的同一系统中管理翻译工作流时，他们会获得最好的体验。例如，当他们翻译一个WordPress网站时，我们在WordPress中提供一个界面。当他们翻译他们的网站设计时，我们在Figma、Sketch等中提供一个界面。

一个原始内容整合Lokalise是一款安装在第三方系统上的应用程序，它是该系统与Lokalise之间的桥梁。它使我们的客户能够选择他们想要翻译的内容，将内容发送给Lokalise，查看翻译状态，并接收已翻译的内容。

期望的用户流是什么?

我们的目标是为我们的客户提供熟悉的体验，遵循跨多个系统的相同流程，包括以下阶段:

• 设置:安装、授权和配置。
• 内容管理:翻译状态和管理界面

用户流程应该如下所示:

阶段

阶段1。安装:安装、授权和配置

该应用程序由用户安装，并指导他们使用Lokalise进行身份验证和集成配置。

步骤1:用户在您的系统中安装应用程序

使用Lokalise的身份验证可以通过生成API令牌或使用OAuth 2访问令牌来执行。请查看以下详细信息。虽然所有端点都支持这两种方法，但建议您使用OAuth 2流。API令牌适合于为单账户使用而设计的快速原型或集成，但为多客户使用或在市场上上市而设计的集成应该使用OAuth 2构建。

步骤2:用户配置应用

配置页面应包含以下参数:

• Lokalise项目——用户应该能够选择一个现有的项目或创建一个新的项目。请注意，应用程序应该只显示用户具有管理访问权限的项目，并包含来自服务的基本语言(作为基本语言或目标语言)。因此，要获取可用的项目，你应该获取所有的项目，并遵循以下步骤:
  • 检查这个团队是否能访问Lokalise API
  • 检查项目类型为LocalizationFiles (:“project_type localization_files”）
  • 检查用户是否是具有此项目管理访问权限的贡献者(使用得到的贡献者端点)
  • 检查此项目是否已禁用分段(“分割”:假的）
  • 检查CMS中的基本语言是否包含在项目中(“语言”)．

项目下拉列表中的第一个选项应该是创建新项目．然后应该显示所有现有项目。

如果用户选择一个现有项目，则应该显示包含基本语言和目标语言的输入。使用得到项目的语言API端点来获取目标语言，而获取项目端点来获取基本语言(base_language_id和base_language_iso参数)．基本语言输入应该被禁用，用户不应该能够更改这种语言。应该启用目标语言输入，以便用户可以向项目添加新的目标语言。

如果用户选择创建新项目，新的输入应显示:

• 项目名称(文本输入)
• 选择一个团队(包含所有用户队伍的下拉列表)-如果用户有多于一个队伍(使用得到团队端点)
• 基本语言是Lokalise项目中的主要初始语言，可能用于内联机器翻译和自动化(您可以使用获得语言端点)
• 目标语言

请注意，CMS中的基本项目语言必须作为基本或目标语言包含在项目中。如果用户没有选择CMS中使用的语言，单击完成，将显示一个错误，项目将不会创建。

下面是一个示例对话框，它可能会在用户选择创建新项目选择:

用户应该能够返回到这个配置页面并更改所有这些设置。如果用户更改了项目，那么应该取消链接(从缓存表中删除)所有键。

身份验证

认证有以下两种方式:

• 通过生成一个API令牌
• 使用OAuth 2访问令牌——这是将被多个用户使用的应用程序的首选选项。

个人访问令牌

API令牌可以在Lokalise上生成个人配置文件- API令牌选项卡．这个令牌应该作为请求头发送到Lokalise APIX-Api-Token．用户必须具有团队所有者角色，才能使用所提供的令牌创建新项目。

你可以在API文档中找到更多细节．

OAuth 2

首先，您应该向Lokalise注册一个新的OAuth 2应用程序，并设置重定向URI。

OAuth 2过程可以分为三个阶段:

• 请求访问代码。
• 使用访问代码发出请求并接收访问令牌(用户可以使用此访问令牌从Lokalise接收数据)。
• 在访问令牌过期后，请求刷新令牌。

你可以在API文档中找到更多细节．

阶段2。翻译状态和管理界面

翻译状态

为了与Lokalise保持同步，这有助于优化通信和用户体验，应用程序必须实现一个内部缓存，为每个内容项保存与Lokalise集成相关的信息。这包括转换状态、最后更新日期和其他所需的元数据。

根据被集成系统的灵活性和能力，可以通过以下两种方式之一实现:

• 实现一个关系数据库，其中所有的信息将被保存，作为应用程序的一部分，并在系统内(即，不在外部服务器上)。
• 扩展内容项对象，并将信息保留为对象本身的一部分。

如果这些选项都不可行，并且需要外部服务器和数据库，则必须由Lokalise构建和管理这些选项。

有关可用的翻译状态，请参阅下面的选项卡块。

管理界面

用户将看到一个翻译管理界面，在这里他们可以管理内容项的翻译工作流。该界面允许他们查看所有内容项的状态，以及搜索特定项并将其推送到Lokalise进行翻译。

所有可以通过API访问的可翻译项都应该显示在这个页面上。我们建议将内容显示为顶级项—例如，如果您的结构是空格>文件夹>文章>标题/描述/正文/等等。，您应该会显示文章列表。当您将一篇文章导出到Lokalise时，将为每个字段创建一个新键(例如，您导出了一篇文章，在Lokalise中创建了3个键——标题、正文和描述)。

每种语言都应该显示为单独的元素(行)。包含3种目标语言的一篇文章将在items表中显示为4行(一行用于基本语言，一行用于每种目标语言)。

一般的描述

管理界面:

选项卡

翻译状态应该显示为不同的选项卡。

请注意，每一种语言的翻译状态是不同的，一个元素(在不同的语言上)可能显示在不同的选项卡下(例如，添加了拉脱维亚语的翻译，西班牙语已发布，意大利语正在进行中)。

可用翻译状态:

表格

本页面应显示以下参数:

• 元素标题(标题的前N个字符和“…”)。如果元素没有标题，那么你应该使用以下选项之一:
  • “内容类型”表示“父元素的标题”。这是元素类型(例如，标题、内容、描述、帖子、富文本、链接、标签或其他)。
  • 下一个文本组件的前N个字符
  • 将项目标记为“未命名”
• 在导出到Lokalise时保存在Lokalise项目中的标记。如果元素有多个标记(例如，文章标题有一个“title”标记，文章描述有一个“description”标记，但是一篇文章只有一行)，我们应该显示所有可能的标记。
• 最后更新日期是在服务中导入或更改已翻译项的日期。
• Language - Languages应该显示为一个筛选器和一个新列。在过滤器中，用户可以选择一种以上的语言。如果选择了一种语言，则只显示该语言的元素。
• “翻译进行中”选项卡: Lokalise的翻译状态。可用的选项有:
  • 没有保存翻译的导出项目为“进行中”
  • 标记为经审查的出口项目为“已处理”(is_reviewed字段中的List keys API调用)
• “翻译已完成”选项卡:元素状态(在您的服务中)。通常状态有以下可能的值:
  • 草稿稿未发表
  • changed -元素被导出到Lokalise后被更改(在这种情况下，元素可以是草稿或发布)
  • 已发布—元素已发布

翻译进行中标签:

翻译完成标签:

CMS系统中可预期的元素状态如下:

过滤器

过滤器应该应用于当前所选选项卡上显示的元素。两个最重要的筛选器应该显示在表的顶部，而其他筛选器可能隐藏在多个过滤器按钮。

我们建议为不同的标签设置不同的重要过滤器:

• 未翻译标签:使用最多的过滤器是语言和标签或标题
• 翻译进行中选项卡:语言和状态
• 翻译是完成标签:语言和标题或标签

过滤器的可用选项应该是:

• 翻译或元素状态(未翻译和翻译进行中选项卡的翻译状态，以及翻译已完成选项卡的元素状态)
• 标签(或用于内容过滤的其他等效选项，具体取决于系统的构建方式)
• 日期(“在之前/之后创建”，“在之前/之后更新”)
• 文本搜索元素中包含的标题或其他文本字段
• 父元素/文件夹/空间/环境
• 内容类型

排序

用户应该能够根据所有显示的字段对元素进行排序:标题、内容类型、最后更新日期。

分页

有两个可能的选择:

• 显示N个元素，并在用户将页面滚动到显示元素的末尾后自动上传下一个N个元素(这是首选选项)
• 显示页面和显示元素的数量，以及用于加载更多项目的按钮:

行动

动作:适用于所有元素的动作:刷新．

在用户单击刷新按钮，应该请求Lokalise的实际翻译状态。元素可以跨选项卡移动，它们的状态应该更新。

此外，界面应该包括针对不同翻译状态的额外操作:

• 的不翻译选项卡应该有出口到Lokalise行动。用户选择一篇文章(或单击Select all复选框)并单击出口到Lokalise按钮。然后应该显示Export设置(请查看下面的详细信息)。
• 的翻译过程中选项卡应该有进口按钮。在用户点击按钮后，所选语言的所有选定项目都应该从Lokalise中导入(请在下面找到详细信息)。

导出的内容

在用户单击之后出口到Lokalise，将显示一个带有Export设置的弹出窗口:

出口设置:

• 选择目标语言。只显示用户已添加到服务的语言。
• 分配标记(默认的、自定义的和初始的)。默认的标签，<空间/环境/其他顶层层次元素在您的系统>,<文章-父元素标题>．例如，如果你要添加Shopify和Lokalise之间的集成，那么标签将Shopify。下一个标记取决于系统中的数据结构。您应该使用顶级元素的标题(名称)(通常是空间/环境/站点名称/文件夹)和父元素的标题(例如，一篇文章有标题、正文和描述字段，所有这些元素都应该有文章标题标记)。
  • 默认情况下会显示它们，但是每个元素都可以删除。
  • 此外，用户应该能够在导出时手动添加任何自定义标记。
• 保存字符限制(如果任何内容项字段/元素有长度限制—字符限制，这些数据也应该传递到Lokalise并保存在Lokalise中)
• 真相的来源-可用的选项是“Lokalise”和“你的系统”。如果用户选择Lokalise作为真相来源，翻译将在Lokalise中更新。但是如果你选择“你的系统”，翻译将不会在Lokalise中更新，即使它们在你的服务中手动更新。
  • 例如，您已经导出、翻译并导入了一篇文章，您需要在那里做一些更改。在这种情况下，管理员更新初始文本，也可以更新译文。如果他们可以直接在你的服务上修复翻译，那么你应该选择你的服务作为真相来源，并在Lokalise中更新翻译。如果只有翻译人员可以修改和更新文本，那么管理者应该只更新初始文本，并将Lokalise设置为真相的来源。
  • 默认情况下，真相来源应为第三方系统。

已导出元素的导出过程(链接到Lokalise键):

• 检查翻译是否包含在正在进行的任务中(可选步骤)。这可以通过以下方法检查:
  • 检索一个关键获取任务ID。
  • 得到钥匙和更新的翻译端点。
  • 如果用户选择了你的服务作为真相的来源把设置，则只能更新基本语言值。您可以使用得到钥匙和更新的翻译端点。

  新元素的导出过程

  • 为每个文本元素添加一个新键。请注意，通常一篇文章(表中的一行)包含几个字段，每个字段将是一个单独的键。这意味着一篇文章可以链接到Lokalise中的多个密钥。
  • 显示导出过程结果:
    • 成功:您可以显示导出了多少项
    • Fail:详细的错误消息，或者至少是引发异常的语句。为用户提供再次运行导出操作的方法。

  导入的内容

  在用户单击之后从Lokalise进口，将显示一个弹出的导入设置。

  

  导入设置:

  • 创建内容的状态——可用选项应该反映系统中的工作流。通常工作流程如下:发布草案>。我们建议将草稿、已发布和相同作为基本项目。默认选项应该与基本项相同。

  进口流程:

  • 获取所选文章所有字段的所有翻译(得到钥匙→得到翻译端点)。应该只导入选定的语言。
  • 更新项目:
    • 已经创建的翻译应该用Lokalise的新值覆盖
    • 新的翻译应该添加到Lokalise -创建新的翻译的文章没有
  • 可能的错误:
    • 在导入之前已删除项-创建一个新项。
    • 语言被删除-该项目应该被跳过。
  • 显示导入操作的结果:
    • 如果流程成功，则应该显示导入、更新和跳过的项的数量。对于跳过的项目，可能会显示详细的错误。
    • 如果进程失败，则会显示一个错误。

  删除应用程序

  用户应该能够删除应用程序。

  在用户删除应用程序后，缓存表中的所有数据(CMS中的文本项和Lokalise中的键之间的链接，以及其他信息，都存储在缓存表中)都应该被删除。如果用户然后重新安装应用程序，元素将不会连接到Lokalise键，并在下一次导出新的Lokalise键将被创建(即使用户选择了初始项目)。

  发展的里程碑

  一步	标题	结果
  阶段1。步骤1	最初的应用程序设置	本地应用程序可供用户安装/重新安装。 这可能在开发过程中是不可能的，直到应用程序被提交到相应的“应用商店”，但这是整个应用程序的线框
  阶段1。步骤2	身份验证实现	当用户安装应用程序时，他们使用OAuth 2或API密钥与Lokalise进行身份验证。范围和凭据保存在应用程序中，以备将来与Lokalise的所有通信。
  阶段1。步骤3	应用程序配置	身份验证之后，用户可以选择Lokalise项目(或创建一个新项目)和将用于此集成的语言。 *请参阅阶段1。安装:安装、授权和配置-用户配置应用程序*
  阶段2。步骤1	Lokalise API实现	创建一个SDK或自定义包装器来实现Lokalise API，以便应用程序可以使用它。
  阶段2。步骤2	Lokalise内容元数据实现	内容对象可以存储在数据库中。 请参见“技术要求”-内容对象
  阶段2。步骤3	翻译管理界面(TMI)	用户将看到一个列出所有可翻译、正在翻译和已翻译的内容的界面。 请参阅“第二阶段”，第3点-一般描述
  阶段2。步骤4	TMI -分类和过滤	用户可以根据状态、标签、日期等对内容进行过滤和排序，以缩小列表范围。
  阶段2。步骤5	TMI -批量操作	用户可以选择一个或多个内容项，并对它们发起操作。
  阶段2。步骤6	行动-导出到Lokalise	选择的内容被导出到Lokalise
  阶段2。步骤7	行动-从Lokalise导入	翻译内容从Lokalise导入

  状态

  为了方便地管理翻译工作流，系统中的每个内容项都有一个与Lokalise中的翻译相关的状态。该状态需要通过扩展内容项对象或创建“映射表”数据库(根据第三方系统中可用的可能性)保存在第三方系统中。

  系统中的每个内容项将具有以下状态之一:

  标题	描述	下一个/之前
  失踪	这个内容项目还没有发送给Lokalise	下一步-正在进行中
  在进行中	此内容项目前正在Lokalise中翻译	以前,失踪 下,做
  完成	翻译在Lokalise中进行审查，但不会导入CMS(要获得审查的翻译，请检查is_reviewed参数得到翻译端点)	先前-正在进行中 下,进口
  进口	翻译后的内容被导入到CMS	以前,做 下,改变了
  改变了	这些内容已被翻译，但文本已在CMS中更新	以前,进口 下一步-正在进行中

  定义

  内容类型-当被集成的系统支持多种类型的内容(例如，“时事通讯”、“博客文章”和“文章”)，每一种都有自己的一组字段和/或独特的结构，这些类型中的每一种被称为“内容类型”。

  内容对象当一个项目被导出到Lokalise时，关于这个项目的附加参数应该存储为内容对象，如翻译状态，Lokalise项目，密钥ID，最后更新日期等。

  翻译状态-是翻译的当前状态。可用选项有:缺失(项目未导出到Lokalise)、正在进行(项目已导出到Lokalise)、已完成(翻译在Lokalise中被标记为评审)、更改(翻译在导入后被更新)。

  刷新内容是CMS比较和设置所有选定项的新翻译状态和最后更新日期时所采取的操作。

  管理界面是包含详细信息和可用操作(导入或导出)的所有元素及其翻译的视图，以便用户能够管理内容项翻译工作流。

  技术指导原则

  代码质量

  • 可交付的代码必须遵循各自语言和框架的编码标准。

  • 交付成果必须包含大量的文档，描述代码的功能和逻辑，可以作为单独的文档，也可以作为嵌入到代码中的内联注释。

  内容对象

  内容对象应该包括以下属性:

  • unique_id这个项目的唯一ID是什么
  • item_id这个项目的ID在你的系统中是多少
  • key_idLokalise钥匙的ID是否与此物品相关
  • project_id是连接的Lokalise项目的ID吗
  • refreshed_at-最近一次刷新的日期和时间
  • updated_at是Lokalise项目更新的日期和时间吗
  • content_type内容的类型(例如，标题、描述、页面、文章等)。
  • field_type是该对象的字段类型(例如，文本、富文本、标记、日期等)。
  • 语言是这个项目的语言吗

  API的限制

  对所有端点的访问限制为每秒6个请求。看到细节在这里．

  MVP的要求

  MVP必须包括以下步骤:

  • app的安装:
    • 用户可以在CMS中安装和删除应用程序/插件。
    • 在用户删除应用程序后，所有关于内容对象的数据都应该被删除。
  • 身份验证:
    • 当用户安装应用程序时，他们使用OAuth 2或API密钥与Lokalise进行身份验证。范围和凭据保存在应用程序中，以备将来与Lokalise的所有通信。
  • 配置(连接到Lokalise项目):
    • 用户能够连接到现有的Lokalise项目。
  • 项选择:
    • 应该为用户提供一个列出所有可翻译、正在翻译和已翻译的内容的界面。
    • 该界面应该包括关于可翻译元素(字段类型、标题等)的主要信息，以及选择任何项进行翻译的可能性。
  • 出口项目:
    • 用户可以导出Lokalise中所有可翻译的内容。在用户单击Export之后，将在选定的Lokalise项目中创建新的键。
  • 进口翻译项目:
    • 用户可以从Lokalise导入翻译后的内容到CMS。

  建议路线图

  预期的大致路线图如下所示: