Cli

🚀 motaword CLI

使用 MotaWord CLI 可以通过多种方式与你的 MotaWord 账户进行交互，从而管理你的翻译和本地化需求。

🚀 快速开始

若要在本地搭建并运行，请按照以下简单步骤操作。

📦 下载预构建二进制文件

使用此 GitHub 仓库中的“发布”功能，为你的相应平台下载应用程序。我们会发布适用于 Linux、Windows 和 MacOS 多种配置的 motaword。

下载地址：发布版本

📦 通过 bash 安装程序安装

我们提供了一个 installer.sh bash 脚本，你可以使用 curl 来在你的工作目录中安装最新版本的 motaword CLI。你可以在这个仓库中找到 installer.sh 脚本。

你可以通过运行以下命令来安装 motaword：

curl -s https://raw.githubusercontent.com/motaword/cli/master/installer.sh | bash

📦 通过 Homebrew 安装

Mac 用户可以通过 Homebrew 轻松安装 motaword：

1. 点击以下命令：

brew tap motaword/homebrew-tap

2. 安装 motaword：

brew install motaword

现在你可以在系统的任何位置运行 motaword。

✨ 主要特性

motaword 允许你访问 MotaWord 平台的各个方面，从提交文件进行翻译到获取报告，从管理你的术语表到样式指南。

💻 使用示例

基础用法

命令类别/父命令

要查看 motaword 支持的所有命令，请运行：

> motaword help

Usage:
motaword [command]

Available Commands:
  async               Manage async operations
  auth                Authentication settings
  continuous-projects Manage your continuous projects
  debug               Debug your MotaWord configuration and environment
  documents           Manage documents
  get-access-token    Retrieve an access token to interact with the API.
  glossaries          Manage glossaries
  help                Help about any command
  help-config         Show CLI configuration help
  help-input          Show CLI input help
  projects            Manage projects
  reports             Manage reports
  search              Manage search operations
  static              Manage static endpoints
  stats               Manage stats
  strings             Manage strings
  styleguides         Manage styleguides
  translate           Instantly translate your content with your existing TM and MT resources. This is an alias to `continuous-projects translate`
  users               Manage users
  webhooks            Manage webhooks

Flags:
  -h, --help                   help for motaword
  -o, --output-format string   Output format [json, yaml] (default "json")
      --profile string         Credentials profile to use for authentication (default "default")
  -q, --query string           Filter / project results using JMESPath
      --raw                    Output result as raw rather than pretty JSON
      --server string          Override server URL
      --v                      Enable WARN level verbose log output
      --verbose                Enable DEBUG level verbose log output, same as --vvv flag
      --vv                     Enable INFO level verbose log output
      --vvv                    Enable DEBUG level verbose log output

Additional help topics:
  motaword blog                Manage blog articles
  motaword clients             Manage client account
  motaword token               Manage token operations

Use "motaword [command] --help" for more information about a command.

这些是命令类别，每个类别下还有子命令。

子命令

假设我们想获取有关我的账户的一些报告：

> motaword reports
Usage:
  motaword reports [command]

Available Commands:
  get-language-pairs-report Returns a report of language pairs.
  get-projects-report       Returns a report of corporate account users.
  get-users-report          Returns a report of corporate account users.

现在我们看到了 reports 类别下的可用命令。让我们使用 get-language-pairs-report 子命令：

> motaword reports get-language-pairs-report

{
  "meta": {
    "paging": {
      "links": {
        "next": null,
        "previous": null,
        "self": {
          "href": "https://api.staging.motaword.com/v0/reports/language-pairs"
        }
      },
      "page": 1,
      "per_page": 2,
      "total_count": 2
    }
  },
  "report": [
    {
      "language_pair": {
        "source_language": "af",
        "target_language": "ak"
      },
      "spending": "343.42",
      "word_count": "2475"
    },
    {
      "language_pair": {
        "source_language": "en-US",
        "target_language": "fr"
      },
      "spending": "11.70",
      "word_count": "195"
    }
  ]
}

大多数命令将返回 JSON 响应。通过使用像 jq 这样的工具，你可以处理这些 JSON 响应。以下是一个从上述响应中获取人类可读输出的示例：

> motaword reports get-language-pairs-report \
| jq '.report[] | "For \(.language_pair.source_language) into \(.language_pair.target_language), we spent $\(.spending)"'


"For af into ak, we spent $343.42"
"For en-US into fr, we spent $11.70"

命令参数

一些命令接受参数和 JSON 有效负载。我们可以使用 --help 标志来查看它们可以接受哪种参数或 JSON 有效负载。

> motaword projects get-project --help

Get single project

Usage:
  motaword projects get-project id [flags]

Flags:
  -h, --help            help for get-project
      --with[] string   Include detailed information. Possible values 'client', 'vendor', 'score'

get-project 命令仅接受 id 参数和 with[] 标志。

一些命令将接受 JSON 有效负载，这些通常是创建/更新命令（例如 HTTP 中的 POST/PUT 请求）。

我们可以通过 --help 查看请求有效负载的格式。请求描述是一个 OpenAPI 规范。以下是一个示例（为简洁起见，删除了描述）：

> motaword reports get-projects-report --help

## Request Schema (application/json)

properties:
  budget_code:
    type: string
  date_from:
    format: date-time
    type: string
  date_to:
    format: date-time
    type: string
  source_languages:
    items:
      type: string
    type: array
  target_languages:
    items:
      type: string
    type: array
  users:
    items:
      format: int64
      type: integer
    type: array
type: object

Usage:
  motaword reports get-projects-report [flags]

Flags:
  -h, --help   help for get-projects-report

根据帮助输出中的请求模式，你可以使用此命令发送此有效负载（这将生成这些日期内的项目报告）：

{
   "date_from":"2021-04-21T16:07:12.727Z",
   "date_to":"2021-05-21T16:07:12.727Z"
}

发送 JSON 有效负载

像上面这样的 JSON 有效负载可以通过将 STDIN 管道传输到命令来发送。

如果你有一个简单的有效负载，你可以这样做：

> echo '{"date_from":"2021-05-21T16:07:12.727Z","date_to":"2021-05-21T16:07:12.727Z"}' \
   | motaword reports get-projects-report

如果你有一个更复杂的有效负载，我们建议先将其放在一个文件中，然后将文件管道传输到命令：

> motaword reports get-projects-report < my-complex-payload.json

📚 详细文档

配置

motaword CLI 应用程序会查找 .motaword/ 目录来进行自我配置。它按以下顺序查找配置：

1. 工作目录
2. $HOME/.motaword
3. /etc/.motaword

我们在这个目录中保存两个文件：

• credentials.json
• config.json

credentials.json 保存你的 MotaWord API 客户端 ID 和客户端密钥。这个文件可以通过 motaword CLI 本身生成。有关更多信息，请参阅下面的身份验证部分。

config.json 允许你配置 motaword CLI 的各个方面，尤其适用于通常在开发和 CI/CD 环境中使用的 motaword translate 命令。你可以在下面了解更多关于 translate 命令的信息。

除非你使用 translate 命令，否则 config.json 文件是可选的。

身份验证

简而言之

添加默认身份验证配置文件以自动创建 .motaword/credentials.json：

motaword auth add-profile client-credentials default MY-CLIENT-ID MY-CLIENT-SECRET

身份验证详情

motaword CLI 需要一个 MotaWord 开发者账户和一个 API 客户端（我们称之为“应用”）。你可以在这里创建一个：https://www.motaword.com/developer

一旦你有了一个开发者账户，就在你的开发者门户上创建一个新应用。现在你可以访问这个应用的 API 客户端 ID 和密钥。

你需要将这些密钥放在 .motaword/credentials.json 文件中，并与你的 motaword CLI 一起使用。credentials.json 文件看起来是这样的：

{
  "profiles": {
    "default": {
      "client_id": "my-client-id",
      "client_secret": "my-client-secret",
      "type": "client-credentials"
    }
  }
}

motaword CLI 允许你有多个身份验证配置文件。在大多数用例中，default 配置文件就足够了，但你可以有多个具有任意名称的配置文件（例如，在上面的示例中，用 secondary-profile 代替 default）。

我们提供了一种自动管理身份验证配置文件的方法：

> motaword auth

Authentication settings

Usage:
  motaword auth [command]

Available Commands:
  add-profile   Add user profile for authentication
  list-profiles List available configured authentication profiles

Flags:
  -h, --help   help for auth

你可以使用以下命令添加一个配置文件：

> motaword auth add-profile client-credentials <name> <client-id> <client-secret>

让我们添加一个默认配置文件：

motaword auth add-profile client-credentials default my-client-id my-client-secret

就是这样！motaword CLI 将为你管理身份验证，包括重用和刷新你的 API 访问令牌。

翻译

不用说，翻译你的文件是我们的 CLI 工具最重要的功能。你可以使用任何文档上传、项目下载/打包命令，但是，有一个独家命令可以为你解决所有问题：

> motaword translate --help

Usage:
  motaword translate [target-language] [flags]

Flags:
  -h, --help   help for translate

这个命令比它看起来要智能得多，并且有自己的一组配置来处理你的文件翻译。这在代码库和 CI/CD 环境中特别有用。

它到底做了什么？

它上传你的语言资源文件，下载翻译后的版本，并将它们放在你的目录结构中的正确位置。让我们深入了解一下。

配置翻译

translate 命令带有高度灵活的配置，以支持所有用例中的翻译。让我们来看看这些配置：

翻译规则

rules 配置非常灵活，可以在许多用例中实现正确的目录结构。每个规则使用类似 glob 的路径模式来收集源文件列表。你可以指定多个规则，将不同的目录结构组合到你的 MotaWord 翻译中。

让我们看看 rules 的默认值：

{
   "source-directory": "src/en",
   "translations-directory": "src/{locale}",
   "rules": {
      "**/*": "{path}/{basename}"
   }
}

这个规则告诉 motaword CLI：

将 src/en 目录中的所有文件作为源文件，并将它们的翻译文件放在 src/{locale} 目录中的相同路径结构中，其中 {locale} 是你的每种翻译语言。

如果你的源目录和翻译目录的组织方式很简单，这可能就足够了。然而，规则可以处理非常复杂的用例。让我们看一个比默认规则稍微复杂一点的例子：

在看这个复杂的例子之前，你应该先看一下规则中的可用变量部分，这会让例子更容易理解。

{
  "source-directory": "src/main/resources/strings",
  "translations-directory": "src/main/resources/translations",
  "rules": {
    "frontend/json/*.json": "{locale}/{path}/{basename}",
    "frontend/**/*.yml": "{locale}/{path}/{filename}.yaml",
    "pot/*.pot": "{locale}/{path}/{basename}",
    "md/*.md": "markdown-translations/{locale}/{path}/{filename}.md"
  },
  "exclude-rules": [
    "pot/passwords*"
  ]
}

像这样的 rules 配置说明了很多事情 :)

要调试和理解你的规则说明了什么，你可以随时运行 motaword debug。它将输出检测到的源文件及其对应的翻译路径。

让我们来分析一下上面的复杂规则：

假设我们要将文件翻译成法语，其语言代码为 fr

1. 将 src/main/resources/strings 作为源文件的基本目录。
2. 将 src/main/resources/translations 作为翻译文件的基本目录。最后一个文件夹与源路径不同。
3. 翻译 src/main/resources/strings/frontend/json/ 目录中的所有 .json 文件，不递归到子目录
   1. 并将它们的（例如法语）翻译文件放入 src/main/resources/translations/fr/frontend/json/ 目录中。
4. 翻译 src/main/resources/strings/frontend/ 目录下的所有 .yml 文件，递归到所有子目录
   1. 并将它们的（例如法语）翻译文件放在 src/main/resources/translations/fr/ 目录下，使用源文件的相应相对路径。
5. 翻译 src/main/resources/strings/md/ 目录中的所有 .md 文件，不递归到子目录
   1. 并将它们的（例如法语）翻译文件放入 src/main/resources/translations/fr/md/ 目录中。
6. 最后，在执行所有这些操作时，排除 src/main/resources/strings/pot 目录中文件名以 passwords 开头的所有文件。

如果你还在阅读，那么你就是一位 motaword 配置专家了 :)

规则中的可用变量

翻译配置示例

查看此仓库中的 ./examples 目录，获取各种配置示例。

调试

所有 motaword CLI 命令都可以使用一些调试标志。使用 --help 查看这些标志。

你可以使用详细标志来配置输出级别：

还有一个 debug 命令可用于你的 config.json 配置文件：

> motaword debug

这将输出检测到的源文件及其对应的翻译路径。

📄 许可证

文档未提及此项目的许可证信息。

📞 联系我们

提供 24/7 免费技术或业务实时聊天支持：https://www.motaword.com