From c2d33f8ec1ad567d685552a791652d80171f69ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mladen=20Jablanovi=C4=87?= Date: Mon, 13 Nov 2023 17:14:13 +0100 Subject: [PATCH] docs: Revert removed general docs part (#464) --- doc/compiled.json | 2 +- main.yaml | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 19b9d71f..ed292b86 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -3,7 +3,7 @@ "info": { "title": "Phrase Strings API Reference", "version": "2.0.0", - "description": "Phrase Strings is a translation management platform for software projects. You can collaborate on language file translation\nwith your team or order translations through our platform. The API allows you to import locale files, download locale files,\ntag keys or interact in other ways with the localization data stored in Phrase Strings for your account.\n", + "description": "Phrase Strings is a translation management platform for software projects. You can collaborate on language file translation with your team or order translations through our platform. The API allows you to import locale files, download locale files, tag keys or interact in other ways with the localization data stored in Phrase Strings for your account.\n\n## API Endpoints\n\n### EU data center\n```\nhttps://api.phrase.com/v2/\n```\n\n### US data center\n\n```\nhttps://api.us.app.phrase.com/v2\n```\n\nThe API is only accessible via HTTPS and the current version is v2, which results in a base URL like: https://api.phrase.com/v2/ depending on the datacenter.\n\n\n## Usage\n\n[curl](http://curl.haxx.se/) is used primarily to send requests to Phrase Strings in the examples. On most you'll find a second variant using the [Phrase Strings API v2 client](https://phrase.com/cli/) that might be more convenient to handle. For further information check its [documentation](https://support.phrase.com/hc/en-us/articles/5808300599068).\n\n## Use of HTTP Verbs\n\nPhrase Strings API v2 tries to use the appropriate HTTP verb for accessing each endpoint according to REST specification where possible:\n\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
VerbDescription
GETRetrieve one or multiple resources
POSTCreate a resource
PUTUpdate a resource
PATCHUpdate a resource (partially)
DELETEDelete a resource
\n
\n\n\n## Identification via User-Agent\n\nYou must include the User-Agent header with the name of your application or project. It might be a good idea to include some sort of contact information as well, so that we can get in touch if necessary (e.g. to warn you about Rate-Limiting or badly formed requests). Examples of excellent User-Agent headers:\n\n```\nUser-Agent: Example Mobile App (example@phrase.com)\nUser-Agent: ACME Inc Python Client (http://example.com/contact)\n```\n\nIf you don't send this header, you will receive a response with 400 Bad Request.\n\n\n## Lists\n\nWhen you request a list of resources, the API will typically only return an array of resources including their most important attributes. For a detailed representation of the resource you should request its detailed representation.\n\nLists are usually [paginated](#pagination).\n\n\n## Parameters\n\nMany endpoints support additional parameters, e.g. for pagination. When passing them in a GET request you can send them as HTTP query string parameters:\n\n```\n$ curl -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects?page=2\"\n```\n\nWhen performing a POST, PUT, PATCH or DELETE request, we recommend sending parameters that are not already included in the URL, as JSON body:\n\n```\n$ curl -H 'Content-Type: application/json' -d '{\"name\":\"My new project\"}' -u EMAIL_OR_ACCESS_TOKEN https://api.phrase.com/v2/projects\n```\n\nEncoding parameters as JSON means better support for types (boolean, integer) and usually better readability. Don't forget to set the correct Content-Type for your request.\n\n*The Content-Type header is omitted in some of the following examples for better readbility.*\n\n\n## Errors\n\n\n### Request Errors\n\nIf a request contains invalid JSON or is missing a required parameter (besides resource attributes), the status `400 Bad Request` is returned:\n\n```\n{\n \"message\": \"JSON could not be parsed\"\n}\n```\n\n\n### Validation Errors\n\nWhen the validation for a resource fails, the status `422 Unprocessable Entity` is returned, along with information on the affected fields:\n\n```\n{\n \"message\": \"Validation Failed\",\n \"errors\": [\n {\n \"resource\": \"Project\",\n \"field\": \"name\",\n \"message\": \"can't be blank\"\n }\n ]\n}\n```\n\n\n## Date Format\n\nTimes and dates are returned and expected in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) date format:\n\n```\nYYYY-MM-DDTHH:MM:SSZ\n```\n\nInstead of 'Z' for UTC time zone you can specify your time zone's locale offset using the following notation:\n\n```\nYYYY-MM-DDTHH:MM:SS±hh:mm\n```\n\nExample for CET (1 hour behind UTC):\n\n```\n2015-03-31T13:00+01:00\n```\n\nPlease note that in HTTP headers, we will use the appropriate recommended date formats instead of ISO 8601.\n\n\n## Authentication\n\nThere are two different ways to authenticate when performing API requests:\n\n* E-Mail and password\n* Oauth Access Token\n\n\n### E-Mail and password\n\nTo get started easily, you can use HTTP Basic authentication with your email and password:\n\n```\n$ curl -u username:password \"https://api.phrase.com/v2/projects\"\n```\n\n\n### OAuth via Access Tokens\n\nYou can create and manage access tokens in your [profile settings](https://app.phrase.com/settings/oauth_access_tokens) in Translation Center or via the [Authorizations API](#tag--Authorizations).\n\nSimply pass the access token as the username of your request:\n\n```\n$ curl -u ACCESS_TOKEN: \"https://api.phrase.com/v2/projects\"\n```\n\nor send the access token via the `Authorization` header field:\n\n```\n$ curl -H \"Authorization: token ACCESS_TOKEN\" https://api.phrase.com/v2/projects\n```\n\n#### Send via parameter\n\nAs JSONP (and other) requests cannot send HTTP Basic Auth credentials, a special query parameter `access_token` can be used:\n\n```\ncurl \"https://api.phrase.com/v2/projects?access_token=ACCESS_TOKEN\"\n```\n\nYou should only use this transport method if sending the authentication via header or Basic authentication is not possible.\n\n### Two-Factor-Authentication\n\nUsers with Two-Factor-Authentication enabled have to send a valid token along their request with certain authentication methods (such as Basic authentication). The necessity of a Two-Factor-Authentication token is indicated by the `X-PhraseApp-OTP: required; :MFA-type` header in the response. The `:MFA-type`field indicates the source of the token, e.g. `app` (refers to your Authenticator application):\n\n```\nX-PhraseApp-OTP: required; app\n```\n\nTo provide a Two-Factor-Authentication token you can simply send it in the header of the request:\n\n```\ncurl -H \"X-PhraseApp-OTP: MFA-TOKEN\" -u EMAIL https://api.phrase.com/v2/projects\n```\n\nSince Two-Factor-Authentication tokens usually expire quickly, we recommend using an alternative authentication method such as OAuth access tokens.\n\n### Multiple Accounts\n\nSome endpoints require the account ID to be specified if the authenticated user is a member of multiple accounts. You can find the eight-digit account ID inside Translation Center by switching to the desired account and then visiting the account details page. If required, you can specify the account just like a normal parameter within the request.\n\n## Pagination\n\nEndpoints that return a list or resources will usually return paginated results and include 25 items by default. To access further pages, use the `page` parameter:\n\n```\n$ curl -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects?page=2\"\n```\n\nSome endpoints also allow a custom page size by using the `per_page` parameter:\n\n```\n$ curl -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects?page=2&per_page=50\"\n```\n\nUnless specified otherwise in the description of the respective endpoint, `per_page` allows you to specify a page size up to 100 items.\n\n\n## Link-Headers\n\nWe provide you with pagination URLs in the [Link Header field](http://tools.ietf.org/html/rfc5988). Make use of this information to avoid building pagination URLs yourself.\n\n```\nLink: ; rel=\"first\", ; rel=\"prev\", ; rel=\"next\", ; rel=\"last\"\n```\n\nPossible `rel` values are:\n\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
ValueDescription
nextURL of the next page of results
lastURL of the last page of results
firstURL of the first page of results
prevURL of the previous page of results
\n
\n\n## Rate Limiting\n\nAll API endpoints are subject to rate limiting to ensure good performance for all customers. The rate limit is calculated per user:\n\n* 1000 requests per 5 minutes\n* 4 concurrent (parallel) requests\n\nFor your convenience we send information on the current rate limit within the response headers:\n\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
HeaderDescription
X-Rate-Limit-LimitNumber of max requests allowed in the current time period
X-Rate-Limit-RemainingNumber of remaining requests in the current time period
X-Rate-Limit-ResetTimestamp of end of current time period as UNIX timestamp
\n
\n\nIf you should run into the rate limit, you will receive the HTTP status code `429: Too many requests`.\n\nIf you should need higher rate limits, [contact us](https://phrase.com/contact).\n\n\n## Conditional GET requests / HTTP Caching\n\n

Note: Conditional GET requests are currently only supported for locales#download and translations#index

\n\nWe will return an ETag or Last-Modified header with most GET requests. When you request a resource we recommend to store this value and submit them on subsequent requests as `If-Modified-Since` and `If-None-Match` headers. If the resource has not changed in the meantime, we will return the status `304 Not Modified` instead of rendering and returning the resource again. In most cases this is less time-consuming and makes your application/integration faster.\n\nPlease note that all conditional requests that return a response with status 304 don't count against your rate limits.\n\n```\n$ curl -i -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects/1234abcd1234abcdefefabcd1234efab/locales/en/download\"\nHTTP/1.1 200 OK\nETag: \"abcd1234abcdefefabcd1234efab1234\"\nLast-Modified: Wed, 28 Jan 2015 15:31:30 UTC\nStatus: 200 OK\n\n$ curl -i -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects/1234abcd1234abcdefefabcd1234efab/locales/en/download\" -H 'If-None-Match: \"abcd1234abcdefefabcd1234efab1234\"'\nHTTP/1.1 304 Not Modified\nETag: \"abcd1234abcdefefabcd1234efab1234\"\nLast-Modified: Wed, 28 Jan 2015 15:31:30 UTC\nStatus: 304 Not Modified\n\n$ curl -i -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects/1234abcd1234abcdefefabcd1234efab/locales/en/download\" -H \"If-Modified-Since: Wed, 28 Jan 2015 15:31:30 UTC\"\nHTTP/1.1 304 Not Modified\nLast-Modified: Wed, 28 Jan 2015 15:31:30 UTC\nStatus: 304 Not Modified\n```\n\n\n## JSONP\n\nThe Phrase Strings API supports [JSONP](http://en.wikipedia.org/wiki/JSONP) for all GET requests in order to deal with cross-domain request issues. Just send a `?callback` parameter along with the request to specify the Javascript function name to be called with the response content:\n\n```\n$ curl \"https://api.phrase.com/v2/projects?callback=myFunction\"\n```\n\nThe response will include the normal output for that endpoint, along with a `meta` section including header data:\n\n```\nmyFunction({\n {\n \"meta\": {\n \"status\": 200,\n ...\n },\n \"data\": [\n {\n \"id\": \"1234abcd1234abc1234abcd1234abc\"\n ...\n }\n ]\n }\n});\n```\n\nTo authenticate a JSONP request, you can send a valid [access token](#overview--oauth-via-access-tokens) as the `?access_token` parameter along the request:\n\n```\n$ curl \"https://api.phrase.com/v2/projects?callback=myFunction&access_token=ACCESS-TOKEN\"\n```\n\n
\n\n
\n\n
\n\n## Usage examples\n\nLearn how to work more efficiently with Phrase Strings API v2 with these\nworkflow-oriented examples.\n\n
\n\n
\n\n
\n\n
\n\n### Find excluded translations with a certain content\n\n GET /v2/projects/:project_id/translations\n\nList excluded translations for the given project which start with the\nterm `PhraseApp`.\n\n#### Parameters\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
sort
\noptional		stringSort criteria. Can be one of: key_name, created_at, updated_at.
\nDefault: key_name
order
\noptional		stringOrder direction. Can be one of: asc, desc.
\nDefault: asc
q
\noptional		stringSpecify a query to find translations by content (including wildcards).
\nNote: Search is limited to 10000 results and may not include recently updated data (depending on the project size).\n
\nThe following qualifiers are supported in the query:
\n\n
    \n
  • id:translation_id,... for queries on a comma-separated list of ids
    • \n
  • tags:XYZ for tags on the translation
    • \n
  • unverified:{true|false} for verification status
    • \n
  • reviewed:{true|false} for reviewed status
    • \n
  • excluded:{true|false} for exclusion status
    • \n
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
    • \n
\nFind more examples here.
\n\n
\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%20excluded:true\" \\\n -u USERNAME_OR_ACCESS_TOKEN\n```\n\n
\n\n
\n\n``` language-bash\nphrase translations list \\\n--project_id \\\n--sort updated_at \\\n--order desc \\\n--query 'PhraseApp* excluded:true' \\\n--access_token \n```\n\n
\n\n\n
\n\n
\n\n
\n\n
\n\n### Find unverified translations with a certain content\n\n GET /v2/projects/:project_id/translations\n\nList unverified translations for the given project which start with the\nterm `PhraseApp` and are not verified.\n\n#### Parameters\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
sort
\noptional		stringSort criteria. Can be one of: key_name, created_at, updated_at.
\nDefault: key_name
order
\noptional		stringOrder direction. Can be one of: asc, desc.
\nDefault: asc
q
\noptional		stringSpecify a query to find translations by content (including wildcards).
\n
Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).\n
\nThe following qualifiers are supported in the query:
\n\n
    \n
  • id:translation_id,... for queries on a comma-separated list of ids
    • \n
  • tags:XYZ for tags on the translation
    • \n
  • unverified:{true|false} for verification status
    • \n
  • reviewed:{true|false} for reviewed status
    • \n
  • excluded:{true|false} for exclusion status
    • \n
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
    • \n
\nFind more examples here.
\n\n
\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/translations?sort=updated_at&order=desc&q=PhraseApp*%20unverified:true\" \\\n -u USERNAME_OR_ACCESS_TOKEN\n```\n\n
\n\n
\n\n``` language-bash\nphrase translations list \\\n--project_id \\\n--sort updated_at \\\n--order desc \\\n--query 'PhraseApp* unverified:true' \\\n--access_token \n```\n\n
\n\n
\n\n
\n\n
\n\n
\n\n### Verify translations selected by query\n\n PATCH /v2/projects/:project_id/translations/verify\n\nVerify all translations that are matching the query `my dog`.\n\n#### Parameters\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
q
\noptional		stringSpecify a query to find translations by content (including wildcards).
\n
Note: Search is limited to 10000 results and may not include recently updated data (depending on the project size).\n
\nThe following qualifiers are supported in the query:
\n\n
    \n
  • id:translation_id,... for queries on a comma-separated list of ids
    • \n
  • tags:XYZ for tags on the translation
    • \n
  • unverified:{true|false} for verification status
    • \n
  • reviewed:{true|false} for reviewed status
    • \n
  • excluded:{true|false} for exclusion status
    • \n
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
    • \n
\nFind more examples here.
sort
\noptional		stringSort criteria. Can be one of: key_name, created_at, updated_at.
\nDefault: key_name
order
\noptional		stringOrder direction. Can be one of: asc, desc.
\nDefault: asc
\n\n
\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/translations/verify\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X PATCH \\\n -d '{\"q\":\"my dog unverified:true\",\"sort\":\"updated_at\",\"order\":\"desc\"}' \\\n -H 'Content-Type: application/json'\n```\n\n
\n\n
\n\n``` language-bash\nphrase translations verify \\\n--project_id \\\n--data '{\"query\":\"\"my dog unverified:true\"\", \"sort\":\"updated_at\", \"order\":\"desc\"}' \\\n--access_token \n```\n\n
\n\n
\n\n
\n\n
\n\n
\n\n### Find recently updated keys\n\n GET /v2/projects/:project_id/keys\n\nFind updated keys with with the `updated_at` qualifier like\n`updated_at:>=2013-02-21T00:00:00Z`. This example returns keys that have\nbeen updated on or after 2013-02-21.\n\n#### Parameters\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
sort
\noptional		stringSort by field. Can be one of: name, created_at, updated_at.
\nDefault: name
order
\noptional		stringOrder direction. Can be one of: asc, desc.
\nDefault: asc
q
\noptional		stringSpecify a query to do broad search for keys by name (including wildcards).
\n
\nThe following qualifiers are also supported in the search term:
\n\n
    \n
  • ids:key_id,... for queries on a comma-separated list of ids
    • \n
  • name:key_name for text queries on exact key names - spaces, commas, and colons need to be escaped with double backslashes
    • \n
  • tags:tag_name to filter for keys with certain tags
    • \n
  • translated:{true|false} for translation status (also requires locale_id to be specified)
    • \n
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
    • \n
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
    • \n
\nFind more examples here.
locale_id
\n\n
\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/keys?sort=updated_at&order=desc&q=updated_at:%3E=2013-02-21T00:00:00Z&locale_id=abcd1234abcd1234abcd1234abcd1234\" \\\n -u USERNAME_OR_ACCESS_TOKEN\n```\n\n
\n\n
\n\n``` language-bash\nphrase keys list \\\n--project_id \\\n--sort updated_at \\\n--order desc \\\n--query \"updated_at:>=2013-02-21T00:00:00Z\" \\\n--locale_id abcd1234abcd1234abcd1234abcd1234 \\\n--access_token \n```\n\n
\n\n
\n\n
\n\n
\n\n
\n\n### Find keys with a certain tag\n\n GET /v2/projects/:project_id/keys\n\nKeys with certain tags can be filtered with the qualifier `tags:`.\n\n#### Parameters\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
q
\noptional		stringSpecify a query to do broad search for keys by name (including wildcards).
\n
\nThe following qualifiers are also supported in the search term:
\n\n
    \n
  • ids:key_id,... for queries on a comma-separated list of ids
    • \n
  • name:key_name for text queries on exact key names - spaces, commas, and colons need to be escaped with double backslashes
    • \n
  • tags:tag_name to filter for keys with certain tags
    • \n
  • translated:{true|false} for translation status (also requires locale_id to be specified)
    • \n
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
    • \n
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
    • \n
\nFind more examples here.
\n\n
\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/keys?q=tags:admin\" \\\n -u USERNAME_OR_ACCESS_TOKEN\n```\n\n
\n\n
\n\n``` language-bash\nphrase keys list \\\n--project_id \\\n--query \"tags:admin\" \\\n--access_token \n```\n\n
\n\n
\n\n
\n\n
\n\n
\n\n### Add tags to collection of keys\n\n PATCH /v2/projects/:project_id/keys/tag\n\nAdd the tags `landing-page` and `release-1.2` to all keys that start\nwith `dog` and are translated in the locale\n`abcd1234abcd1234abcd1234abcd1234`.\n\n#### Parameters\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
q
\noptional		stringSpecify a query to do broad search for keys by name (including wildcards).
\n
\nThe following qualifiers are also supported in the search term:
\n\n
    \n
  • ids:key_id,... for queries on a comma-separated list of ids
    • \n
  • name:key_name for text queries on exact key names - whitespaces need to be prefixed with a backspace (\"\\\")
    • \n
  • tags:tag_name to filter for keys with certain tags
    • \n
  • translated:{true|false} for translation status (also requires locale_id to be specified)
    • \n
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
    • \n
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
    • \n
\nFind more examples here.
tagsstringTag or comma-separated list of tags to add to the matching collection of keys
locale_id
\noptional		idLocale used to determine the translation state of a key when filtering for untranslated or translated keys.
\n\n
\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/keys/tag\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X PATCH \\\n -d '{\"q\":\"dog* translated:true\",\"tags\":\"landing-page,release-1.2\",\"locale_id\":\"abcd1234abcd1234abcd1234abcd1234\"}' \\\n -H 'Content-Type: application/json'\n```\n\n
\n\n
\n\n``` language-bash\nphrase keys tag \\\n--project_id \\\n--data '{\"query\":\"'dog* translated:true'\", \"tags\":\"landing-page,release-1.2\", \"locale_id\":\"abcd1234abcd1234abcd1234abcd1234\"}' \\\n--access_token \n```\n\n
\n\n
\n\n
\n\n
\n\n
\n\n### Remove tags from collection of keys\n\n PATCH /v2/projects/:project_id/keys/untag\n\nRemove the tags `landing-page` and `release-1.2` from all keys that\nstart with `dog` and are translated in the locale\n`abcd1234abcd1234abcd1234abcd1234`.\n\n#### Parameters\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
q
\noptional		stringSpecify a query to do broad search for keys by name (including wildcards).
\n
\nThe following qualifiers are also supported in the search term:
\n\n
    \n
  • ids:key_id,... for queries on a comma-separated list of ids
    • \n
  • name:key_name for text queries on exact key names - whitespaces need to be prefixed with a backspace (\"\\\")
    • \n
  • tags:tag_name to filter for keys with certain tags
    • \n
  • translated:{true|false} for translation status (also requires locale_id to be specified)
    • \n
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
    • \n
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
    • \n
\nFind more examples here.
tagsstringTag or comma-separated list of tags to remove from the matching collection of keys
locale_id
\noptional		idLocale used to determine the translation state of a key when filtering for untranslated or translated keys.
\n\n
\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/keys/untag\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X PATCH \\\n -d '{\"q\":\"dog* translated:true\",\"tags\":\"landing-page,release-1.2\",\"locale_id\":\"abcd1234abcd1234abcd1234abcd1234\"}' \\\n -H 'Content-Type: application/json'\n```\n\n
\n\n
\n\n``` language-bash\nphrase keys untag \\\n--project_id \\\n--data '{\"query\":\"'dog* translated:true'\", \"tags\":\"landing-page,release-1.2\", \"locale_id\":\"abcd1234abcd1234abcd1234abcd1234\"}' \\\n--access_token \n```\n\n
\n\n
\n\n
\n\n
\n\n
\n\n### Find keys with broad text match\n\n GET /v2/projects/:project_id/keys\n\nExample query `my dog`\n\n#### Parameters\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
q
\noptional		stringSpecify a query to do broad search for keys by name (including wildcards).
\n
\nThe following qualifiers are also supported in the search term:
\n\n
    \n
  • ids:key_id,... for queries on a comma-separated list of ids
    • \n
  • name:key_name for text queries on exact key names - whitespaces need to be prefixed with a backspace (\"\\\")
    • \n
  • tags:tag_name to filter for keys with certain tags
    • \n
  • translated:{true|false} for translation status (also requires locale_id to be specified)
    • \n
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
    • \n
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
    • \n
\nFind more examples here.
\n\n
\n\n#### Matches\n\n**My dog** is lazy\n **my dog** is lazy\n angry **dog** in **my** house\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/keys?q=my%20dog\" \\\n -u USERNAME_OR_ACCESS_TOKEN\n```\n\n
\n\n
\n\n``` language-bash\nphrase keys list \\\n--project_id \\\n--query \"my dog\" \\\n--access_token \n```\n\n
\n\n
\n\n
\n\n
\n\n
\n\n### Find keys with exact text match\n\n GET /v2/projects/:project_id/keys\n\nExample query `\"my dog is lazy\"` (note backslashes before any whitespace\ncharacter in the example query)\n\n#### Parameters\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
q
\noptional		stringSpecify a query to do broad search for keys by name (including wildcards).
\n
\nThe following qualifiers are also supported in the search term:
\n\n
    \n
  • ids:key_id,... for queries on a comma-separated list of ids
    • \n
  • name:key_name for text queries on exact key names - whitespaces need to be prefixed with a backspace (\"\\\")
    • \n
  • tags:tag_name to filter for keys with certain tags
    • \n
  • translated:{true|false} for translation status (also requires locale_id to be specified)
    • \n
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
    • \n
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
    • \n
\nFind more examples here.
\n\n
\n\n#### Matches\n\n~~My dog is lazy~~\n**my dog is lazy**\n ~~angry dog in my house~~\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/keys?q=name:my%5C%20dog%5C%20is%5C%20lazy\" \\\n -u USERNAME_OR_ACCESS_TOKEN\n```\n\n
\n\n
\n\n``` language-bash\nphrase keys list \\\n--project_id \\\n--query \"name:my\\ dog\\ is\\ lazy\" \\\n--access_token \n```\n\n
\n\n
\n\n
\n\n
\n\n
\n\n### Find keys with wildcard character matching\n\n GET /v2/projects/:project_id/keys\n\nExample query `*dog is*`\n\n#### Parameters\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeDescription
q
\noptional		stringSpecify a query to do broad search for keys by name (including wildcards).
\n
\nThe following qualifiers are also supported in the search term:
\n\n
    \n
  • ids:key_id,... for queries on a comma-separated list of ids
    • \n
  • name:key_name for text queries on exact key names - whitespaces need to be prefixed with a backspace (\"\\\")
    • \n
  • tags:tag_name to filter for keys with certain tags
    • \n
  • translated:{true|false} for translation status (also requires locale_id to be specified)
    • \n
  • updated_at:{>=|<=}2013-02-21T00:00:00Z for date range queries
    • \n
  • unmentioned_in_upload:upload_id to filter keys unmentioned within upload
    • \n
\nFind more examples here.
\n\n
\n\n#### Matches\n\nMy **dog is** lazy\n my **dog is** lazy\n ~~angry dog in my house~~\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/keys?q=*dog%20is*\" \\\n -u USERNAME_OR_ACCESS_TOKEN\n```\n\n
\n\n
\n\n``` language-bash\nphrase keys list \\\n--project_id \\\n--query '*dog is*' \\\n--access_token \n```\n\n
\n\n
\n\n
\n\n
\n\n
\n\n### Upload an Excel file with several translations\n\n POST /v2/projects/:project_id/uploads\n\nSuppose you have an excel file where the 'A' column contains the key\nnames, the 'B' column contains English translations, the 'C' column\ncontains German translations and the 'D' column contains comments.\nFurthermore, the actual content starts in the second row, since the\nfirst row is reserved for a header. You can upload this file and import\nall translations at once\\!\n\n#### Parameters\n\n
\n\n| Name | Type | Description |\n| ----------------------------------- | -------- | ----------------------------------------------------------- |\n| `file` | `file` | File to be imported |\n| `file_format` | `string` | File format. Auto-detected when possible and not specified. |\n| `locale_mapping[en]` | `string` | Name of the column containing translations for locale en. |\n| `locale_mapping[de]` | `string` | Name of the column containing translations for locale de. |\n| `format_options[comment_column]` | `string` | Name of the column containing descriptions for keys. |\n| `format_options[tag_column]` | `string` | Name of the column containing tags for keys. |\n| `format_options[key_name_column]` | `string` | Name of the column containing the names of the keys. |\n| `format_options[first_content_row]` | `string` | Name of the first row containing actual translations. |\n\n
\n\n
\n\n
\n\n#### Example Request\n\n
\n\n``` language-bash\ncurl \"https://api.phrase.com/v2/projects/:project_id/uploads\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -F file=@/path/to/my/file.xlsx \\\n -F file_format=xlsx \\\n -F locale_mapping[en]=B \\\n -F locale_mapping[de]=C \\\n -F format_options[comment_column]=D \\\n -F format_options[tag_column]=E \\\n -F format_options[key_name_column]=A \\\n -F format_options[first_content_row]=2\n```\n\n
\n\n
\n\n``` language-bash\nphrase uploads create \\\n--project_id \\\n--file /path/to/my/file.xlsx \\\n--file_format xlsx \\\n--locale_id abcd1234cdef1234abcd1234cdef1234 \\\n--tags awesome-feature,needs-proofreading \\\n--locale_mapping '{\"en\": \"B\", \"de\": \"C\"}' \\\n--format_options '{\"comment_column\": \"D\", \"tag_column\": \"E\", \"key_name_column\": \"A\", \"first_content_row\": \"2\"}' \\\n--access_token \n```\n\n
\n\n
\n\n
\n\n
\n", "contact": { "name": "Phrase Support", "url": "https://developers.phrase.com/api/", diff --git a/main.yaml b/main.yaml index 37359455..f2e2d412 100644 --- a/main.yaml +++ b/main.yaml @@ -3,10 +3,8 @@ openapi: 3.0.3 info: title: Phrase Strings API Reference version: 2.0.0 - description: | - Phrase Strings is a translation management platform for software projects. You can collaborate on language file translation - with your team or order translations through our platform. The API allows you to import locale files, download locale files, - tag keys or interact in other ways with the localization data stored in Phrase Strings for your account. + description: + $ref: "./intro.md" contact: name: Phrase Support