diff --git a/doc/compiled.json b/doc/compiled.json index 4c761c45..2e83a65a 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -115,9 +115,15 @@ { "name": "Keys" }, + { + "name": "Linked Keys" + }, { "name": "Locales" }, + { + "name": "Locale Downloads" + }, { "name": "Members", "description": "With the members endpoints you can do basic [team and user management](https://support.phrase.com/hc/en-us/articles/5709742418716) via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them.\n" @@ -1699,6 +1705,90 @@ "updated_at": "2015-01-28T09:52:53Z" } }, + "locale_download": { + "type": "object", + "title": "Async Locale Download", + "properties": { + "id": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "processing", + "completed", + "error" + ], + "description": "The status of the download request. Possible values are `processing`, `completed`, and `error`.\n" + }, + "result": { + "type": "object", + "properties": { + "url": { + "type": "string", + "format": "uri", + "description": "The URL to the download file. This URL is valid for 15 minutes.\n" + } + } + }, + "params": { + "type": "object", + "description": "The parameters of the download request.\n", + "properties": { + "file_format": { + "type": "string" + }, + "locale_id": { + "type": "string" + }, + "tags": { + "type": "string" + }, + "branch": { + "type": "string" + }, + "include_empty_translations": { + "type": "boolean" + }, + "include_translated_keys": { + "type": "boolean" + }, + "include_unverified_translations": { + "type": "boolean" + } + } + }, + "error": { + "type": "string" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "completed_at": { + "type": "string", + "format": "date-time" + } + }, + "example": { + "id": "abcd1234cdef1234abcd1234cdef1234", + "status": "completed", + "result": { + "url": "https://example.com/locales/abcd1234cdef1234abcd1234cdef1234/download?file_format=yml" + }, + "params": { + "file_format": "yml", + "locale_id": "abcd1234cdef1234abcd1234cdef1234", + "tags": "feature1,feature2", + "branch": "my-feature-branch", + "include_empty_translations": true, + "include_translated_keys": true, + "include_unverified_translations": true + }, + "created_at": "2015-01-28T09:52:53Z", + "completed_at": "2015-01-28T09:52:53Z" + } + }, "locale_statistics": { "type": "object", "title": "locale_statistics", @@ -8731,6 +8821,235 @@ "x-cli-version": "2.6.4" } }, + "/projects/{project_id}/locales/{locale_id}/downloads": { + "post": { + "summary": "Initiate async download of a locale", + "description": "Prepare a locale for download in a specific file format.", + "operationId": "locale_download/create", + "tags": [ + "Locale Downloads" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/If-Modified-Since" + }, + { + "$ref": "#/components/parameters/If-None-Match" + }, + { + "$ref": "#/components/parameters/project_id" + }, + { + "$ref": "#/components/parameters/locale_id" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "title": "locale_download/create/parameters", + "required": [ + "file_format" + ], + "properties": { + "file_format": { + "description": "File format name. See the format guide for all supported file formats.", + "type": "string", + "example": "yml" + }, + "branch": { + "description": "specify the branch to use", + "type": "string", + "example": "my-feature-branch" + }, + "tags": { + "description": "Limit results to keys tagged with a list of comma separated tag names.", + "type": "string", + "example": "feature1,feature2" + }, + "include_empty_translations": { + "description": "Indicates whether keys without translations should be included in the output as well.", + "example": true, + "type": "boolean" + }, + "exclude_empty_zero_forms": { + "description": "Indicates whether zero forms should be included when empty in pluralized keys.", + "example": true, + "type": "boolean" + }, + "include_translated_keys": { + "description": "Include translated keys in the locale file. Use in combination with include_empty_translations to obtain only untranslated keys.", + "example": true, + "type": "boolean" + }, + "keep_notranslate_tags": { + "description": "Indicates whether [NOTRANSLATE] tags should be kept.", + "type": "boolean", + "example": true + }, + "format_options": { + "description": "Additional formatting and render options. See the format guide for a list of options available for each format. Specify format options like this: ...&format_options[foo]=bar", + "type": "object", + "properties": {} + }, + "encoding": { + "description": "Enforces a specific encoding on the file contents. Valid options are \"UTF-8\", \"UTF-16\" and \"ISO-8859-1\".", + "example": "UTF-8", + "type": "string" + }, + "include_unverified_translations": { + "description": "if set to false unverified translations are excluded", + "example": true, + "type": "boolean" + }, + "use_last_reviewed_version": { + "description": "If set to true the last reviewed version of a translation is used. This is only available if the review workflow is enabled for the project.", + "type": "boolean", + "example": null + }, + "fallback_locale_id": { + "description": "If a key has no translation in the locale being downloaded the translation in the fallback locale will be used. Provide the ID of the locale that should be used as the fallback. Requires include_empty_translations to be set to true.", + "type": "string", + "example": "abcd1234abcd1234abcd1234abcd1234" + }, + "source_locale_id": { + "description": "Provides the source language of a corresponding job as the source language of the generated locale file. This parameter will be ignored unless used in combination with a tag parameter indicating a specific job.", + "example": "abcd1234abcd1234abcd1234abcd1234", + "type": "string" + }, + "custom_metadata_filters": { + "description": "Custom metadata filters. Provide the name of the metadata field and the value to filter by. Only keys with matching metadata will be included in the download.\n", + "type": "object", + "properties": {} + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/locale_download" + } + } + }, + "headers": { + "X-Rate-Limit-Limit": { + "$ref": "#/components/headers/X-Rate-Limit-Limit" + }, + "X-Rate-Limit-Remaining": { + "$ref": "#/components/headers/X-Rate-Limit-Remaining" + }, + "X-Rate-Limit-Reset": { + "$ref": "#/components/headers/X-Rate-Limit-Reset" + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "x-code-samples": [ + { + "lang": "Curl", + "source": "\ncurl \"https://api.phrase.com/v2/projects/:project_id/locales/:locale_id/downloads\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -d '{\"branch\":\"my-feature-branch\",\"file_format\":\"yml\",\"tags\":\"feature1,feature\",\"custom_metadata_filters\":{\"tone\":\"friendly\"}}' \\\n -H 'Content-Type: application/json'" + }, + { + "lang": "CLI v2", + "source": "phrase locale_downloads create \\\n--project_id \\\n--locale_id \\\n--branch my-feature-branch \\\n--file_format yml \\\n--tags feature1,feature2 \\\n--access_token " + } + ], + "x-cli-version": "2.29.0" + } + }, + "/projects/{project_id}/locales/{locale_id}/downloads/{id}": { + "get": { + "summary": "Show status of an async locale download", + "description": "Show status of already started async locale download. If the download is finished, the download link will be returned.", + "operationId": "locale_download/show", + "tags": [ + "Locale Downloads" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/If-Modified-Since" + }, + { + "$ref": "#/components/parameters/If-None-Match" + }, + { + "$ref": "#/components/parameters/project_id" + }, + { + "$ref": "#/components/parameters/locale_id" + }, + { + "$ref": "#/components/parameters/id" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/locale_download" + } + } + }, + "headers": { + "X-Rate-Limit-Limit": { + "$ref": "#/components/headers/X-Rate-Limit-Limit" + }, + "X-Rate-Limit-Remaining": { + "$ref": "#/components/headers/X-Rate-Limit-Remaining" + }, + "X-Rate-Limit-Reset": { + "$ref": "#/components/headers/X-Rate-Limit-Reset" + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "x-code-samples": [ + { + "lang": "Curl", + "source": "curl \"https://api.phrase.com/v2/projects/:project_id/locales/:locale_id/downloads/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN" + }, + { + "lang": "CLI v2", + "source": "phrase locale_downloads show \\\n--project_id \\\n--locale_id \\\n--id \n--access_token " + } + ], + "x-cli-version": "2.29.0" + } + }, "/accounts/{account_id}/distributions": { "get": { "summary": "List distributions", diff --git a/main.yaml b/main.yaml index 4bdf243e..a7afecb6 100644 --- a/main.yaml +++ b/main.yaml @@ -134,7 +134,9 @@ tags: - name: Job Templates - name: Jobs - name: Keys + - name: Linked Keys - name: Locales + - name: Locale Downloads - name: Members description: | With the members endpoints you can do basic [team and user management](https://support.phrase.com/hc/en-us/articles/5709742418716) via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them. diff --git a/paths.yaml b/paths.yaml index b943eb48..7e3b3ca8 100644 --- a/paths.yaml +++ b/paths.yaml @@ -108,6 +108,12 @@ "/projects/{project_id}/locales/{id}/download": get: "$ref": "./paths/locales/download.yaml" +"/projects/{project_id}/locales/{locale_id}/downloads": + post: + "$ref": "./paths/locale_downloads/create.yaml" +"/projects/{project_id}/locales/{locale_id}/downloads/{id}": + get: + "$ref": "./paths/locale_downloads/show.yaml" "/accounts/{account_id}/distributions": get: "$ref": "./paths/distributions/index.yaml" diff --git a/paths/locale_downloads/create.yaml b/paths/locale_downloads/create.yaml new file mode 100644 index 00000000..140c6910 --- /dev/null +++ b/paths/locale_downloads/create.yaml @@ -0,0 +1,119 @@ +--- +summary: Initiate async download of a locale +description: Prepare a locale for download in a specific file format. +operationId: locale_download/create +tags: + - Locale Downloads +parameters: + - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" + - "$ref": "../../parameters.yaml#/If-Modified-Since" + - "$ref": "../../parameters.yaml#/If-None-Match" + - "$ref": "../../parameters.yaml#/project_id" + - "$ref": "../../parameters.yaml#/locale_id" +requestBody: + required: true + content: + application/json: + schema: + type: object + title: locale_download/create/parameters + required: + - file_format + properties: + file_format: + description: File format name. See the format guide for all supported file formats. + type: string + example: yml + branch: + description: specify the branch to use + type: string + example: my-feature-branch + tags: + description: Limit results to keys tagged with a list of comma separated tag names. + type: string + example: feature1,feature2 + include_empty_translations: + description: Indicates whether keys without translations should be included in the output as well. + example: true + type: boolean + exclude_empty_zero_forms: + description: Indicates whether zero forms should be included when empty in pluralized keys. + example: true + type: boolean + include_translated_keys: + description: Include translated keys in the locale file. Use in combination with include_empty_translations to obtain only untranslated keys. + example: true + type: boolean + keep_notranslate_tags: + description: Indicates whether [NOTRANSLATE] tags should be kept. + type: boolean + example: true + format_options: + description: 'Additional formatting and render options. See the format guide for a list of options available for each format. Specify format options like this: ...&format_options[foo]=bar' + # example: + type: object + properties: {} + encoding: + description: Enforces a specific encoding on the file contents. Valid options are "UTF-8", "UTF-16" and "ISO-8859-1". + example: UTF-8 + type: string + include_unverified_translations: + description: if set to false unverified translations are excluded + example: true + type: boolean + use_last_reviewed_version: + description: If set to true the last reviewed version of a translation is used. This is only available if the review workflow is enabled for the project. + type: boolean + example: + fallback_locale_id: + description: If a key has no translation in the locale being downloaded the translation in the fallback locale will be used. Provide the ID of the locale that should be used as the fallback. Requires include_empty_translations to be set to true. + type: string + example: abcd1234abcd1234abcd1234abcd1234 + source_locale_id: + description: Provides the source language of a corresponding job as the source language of the generated locale file. This parameter will be ignored unless used in combination with a tag parameter indicating a specific job. + example: abcd1234abcd1234abcd1234abcd1234 + type: string + custom_metadata_filters: + description: | + Custom metadata filters. Provide the name of the metadata field and the value to filter by. Only keys with matching metadata will be included in the download. + type: object + properties: {} +responses: + "201": + description: Created + content: + application/json: + schema: + "$ref": "../../schemas/locale_download.yaml#/locale_download" + headers: + X-Rate-Limit-Limit: + "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" + X-Rate-Limit-Remaining: + "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" + X-Rate-Limit-Reset: + "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + "400": + "$ref": "../../responses.yaml#/400" + "404": + "$ref": "../../responses.yaml#/404" + "429": + "$ref": "../../responses.yaml#/429" +x-code-samples: + - lang: Curl + source: |- + + curl "https://api.phrase.com/v2/projects/:project_id/locales/:locale_id/downloads" \ + -u USERNAME_OR_ACCESS_TOKEN \ + -X POST \ + -d '{"branch":"my-feature-branch","file_format":"yml","tags":"feature1,feature","custom_metadata_filters":{"tone":"friendly"}}' \ + -H 'Content-Type: application/json' + - lang: CLI v2 + source: |- + phrase locale_downloads create \ + --project_id \ + --locale_id \ + --branch my-feature-branch \ + --file_format yml \ + --tags feature1,feature2 \ + --access_token +x-cli-version: "2.29.0" diff --git a/paths/locale_downloads/show.yaml b/paths/locale_downloads/show.yaml new file mode 100644 index 00000000..0d4ba340 --- /dev/null +++ b/paths/locale_downloads/show.yaml @@ -0,0 +1,46 @@ +--- +summary: Show status of an async locale download +description: Show status of already started async locale download. If the download is finished, the download link will be returned. +operationId: locale_download/show +tags: + - Locale Downloads +parameters: + - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" + - "$ref": "../../parameters.yaml#/If-Modified-Since" + - "$ref": "../../parameters.yaml#/If-None-Match" + - "$ref": "../../parameters.yaml#/project_id" + - "$ref": "../../parameters.yaml#/locale_id" + - "$ref": "../../parameters.yaml#/id" +responses: + "200": + description: OK + content: + application/json: + schema: + "$ref": "../../schemas/locale_download.yaml#/locale_download" + headers: + X-Rate-Limit-Limit: + "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" + X-Rate-Limit-Remaining: + "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" + X-Rate-Limit-Reset: + "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + "400": + "$ref": "../../responses.yaml#/400" + "404": + "$ref": "../../responses.yaml#/404" + "429": + "$ref": "../../responses.yaml#/429" +x-code-samples: + - lang: Curl + source: |- + curl "https://api.phrase.com/v2/projects/:project_id/locales/:locale_id/downloads/:id" \ + -u USERNAME_OR_ACCESS_TOKEN + - lang: CLI v2 + source: |- + phrase locale_downloads show \ + --project_id \ + --locale_id \ + --id + --access_token +x-cli-version: "2.29.0" diff --git a/schemas.yaml b/schemas.yaml index e5a519fc..04a157e5 100644 --- a/schemas.yaml +++ b/schemas.yaml @@ -56,6 +56,8 @@ schemas: "$ref": schemas/locale_preview.yaml#/locale_preview locale: "$ref": schemas/locale.yaml#/locale + locale_download: + "$ref": schemas/locale_download.yaml#/locale_download locale_statistics: "$ref": schemas/locale_statistics.yaml#/locale_statistics locale_report: diff --git a/schemas/locale_download.yaml b/schemas/locale_download.yaml new file mode 100644 index 00000000..fcff8ae2 --- /dev/null +++ b/schemas/locale_download.yaml @@ -0,0 +1,62 @@ +--- +locale_download: + type: object + title: Async Locale Download + properties: + id: + type: string + status: + type: string + enum: [processing, completed, error] + description: | + The status of the download request. Possible values are `processing`, `completed`, and `error`. + result: + type: object + properties: + url: + type: string + format: uri + description: | + The URL to the download file. This URL is valid for 15 minutes. + params: + type: object + description: | + The parameters of the download request. + properties: + file_format: + type: string + locale_id: + type: string + tags: + type: string + branch: + type: string + include_empty_translations: + type: boolean + include_translated_keys: + type: boolean + include_unverified_translations: + type: boolean + error: + type: string + created_at: + type: string + format: date-time + completed_at: + type: string + format: date-time + example: + id: abcd1234cdef1234abcd1234cdef1234 + status: completed + result: + url: https://example.com/locales/abcd1234cdef1234abcd1234cdef1234/download?file_format=yml + params: + file_format: yml + locale_id: abcd1234cdef1234abcd1234cdef1234 + tags: feature1,feature2 + branch: my-feature-branch + include_empty_translations: true + include_translated_keys: true + include_unverified_translations: true + created_at: '2015-01-28T09:52:53Z' + completed_at: '2015-01-28T09:52:53Z'