Skip to content

fix(API): improve get /formats documentation #1196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sven Dunemann (forelabs) merged 1 commit into from
Jun 17, 2026
Merged

fix(API): improve get /formats documentation #1196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 86 additions & 13 deletions doc/compiled.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1902,36 +1902,68 @@
"format": {
"type": "object",
"title": "format",
"required": [
"name",
"api_name",
"description",
"extension",
"default_encoding",
"importable",
"exportable",
"default_file",
"renders_default_locale",
"includes_locale_information"
],
"properties": {
"name": {
"type": "string"
"type": "string",
"description": "Human-readable display name of the format.",
"example": "Ruby/Rails YAML"
},
"api_name": {
"type": "string"
"type": "string",
"description": "Identifier used to reference this format in API requests, such as the file_format parameter on the uploads and downloads endpoints.",
"example": "yml"
},
"description": {
"type": "string"
"type": "string",
"description": "Human-readable summary of the format and its typical use case.",
"example": "YAML file format for use with Ruby/Rails applications"
},
"extension": {
"type": "string"
"type": "string",
"description": "Default file extension associated with this format.",
"example": "yml"
},
"default_encoding": {
"type": "string"
"type": "string",
"description": "Default character encoding used when reading or writing files in this format.",
"example": "UTF-8"
},
"importable": {
"type": "boolean"
"type": "boolean",
"description": "Whether locale files can be imported using this format.",
"example": true
},
"exportable": {
"type": "boolean"
"type": "boolean",
"description": "Whether locale files can be exported using this format.",
"example": true
},
"default_file": {
"type": "string"
"type": "string",
"description": "Conventional file path pattern for this format. Contains locale_name as a placeholder for the locale identifier.",
"example": "./config/locales/<locale_name>.yml"
},
"renders_default_locale": {
"type": "boolean"
"type": "boolean",
"description": "When true, exported files contain the default locale's content for any key that has no translation in the target locale.",
"example": false
},
"includes_locale_information": {
"type": "boolean"
"type": "boolean",
"description": "When true, files in this format embed locale information so Phrase can detect the locale automatically on import.",
"example": false
}
},
"example": {
Expand All @@ -1944,7 +1976,7 @@
"exportable": true,
"default_file": "./config/locales/<locale_name>.yml",
"renders_default_locale": false,
"includes_locale_information": true
"includes_locale_information": false
}
},
"project": {
Expand Down Expand Up @@ -5530,7 +5562,7 @@
"/formats": {
"get": {
"summary": "List formats",
"description": "Get a handy list of all localization file formats supported in Phrase.",
"description": "Returns all file formats that Phrase Strings supports. Use the api_name value\nfrom each format as the file_format parameter when uploading or downloading\nlocale files. Not every format supports both directions: check the importable\nand exportable fields before using a format in a workflow. This endpoint does\nnot require authentication and is not subject to rate limiting.\n",
"operationId": "formats/list",
"tags": [
"Formats"
Expand All @@ -5545,8 +5577,49 @@
"items": {
"$ref": "#/components/schemas/format"
}
},
"examples": {
"default": {
"value": [
{
"name": "Ruby/Rails YAML",
"api_name": "yml",
"description": "YAML file format for use with Ruby/Rails applications",
"extension": "yml",
"default_encoding": "UTF-8",
"importable": true,
"exportable": true,
"default_file": "./config/locales/<locale_name>.yml",
"renders_default_locale": false,
"includes_locale_information": false
},
{
"name": "Simple JSON",
"api_name": "simple_json",
"description": "A flat key/value JSON format",
"extension": "json",
"default_encoding": "UTF-8",
"importable": true,
"exportable": true,
"default_file": "./config/locales/<locale_name>.json",
"renders_default_locale": false,
"includes_locale_information": false
}
]
}
}
}
},
"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": {
Expand All @@ -5556,7 +5629,7 @@
"x-code-samples": [
{
"lang": "Curl",
"source": "curl \"https://api.phrase.com/v2/formats\""
"source": "curl \"https://api.phrase.com/v2/formats\" \\\n -u USERNAME_OR_ACCESS_TOKEN"
},
{
"lang": "CLI v2",
Expand Down
41 changes: 39 additions & 2 deletions paths/formats/index.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
---
summary: List formats
description: Get a handy list of all localization file formats supported in Phrase.
description: |
Returns all file formats that Phrase Strings supports. Use the api_name value
from each format as the file_format parameter when uploading or downloading
locale files. Not every format supports both directions: check the importable
and exportable fields before using a format in a workflow. This endpoint does
not require authentication and is not subject to rate limiting.
operationId: formats/list
tags:
- Formats
Expand All @@ -13,11 +18,43 @@ responses:
type: array
items:
"$ref": "../../schemas/format.yaml#/format"
examples:
default:
value:
- name: Ruby/Rails YAML
api_name: yml
description: YAML file format for use with Ruby/Rails applications
extension: yml
default_encoding: UTF-8
importable: true
exportable: true
default_file: "./config/locales/<locale_name>.yml"
renders_default_locale: false
includes_locale_information: false
- name: Simple JSON
api_name: simple_json
description: A flat key/value JSON format
extension: json
default_encoding: UTF-8
importable: true
exportable: true
default_file: "./config/locales/<locale_name>.json"
renders_default_locale: false
includes_locale_information: false
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"
x-code-samples:
- lang: Curl
source: curl "https://api.phrase.com/v2/formats"
source: |-
curl "https://api.phrase.com/v2/formats" \
-u USERNAME_OR_ACCESS_TOKEN
- lang: CLI v2
source: |-
phrase formats list \
Expand Down
42 changes: 41 additions & 1 deletion schemas/format.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,27 +2,67 @@
format:
type: object
title: format
required:
- name
- api_name
- description
- extension
- default_encoding
- importable
- exportable
- default_file
- renders_default_locale
- includes_locale_information
properties:
name:
type: string
description: Human-readable display name of the format.
example: Ruby/Rails YAML
api_name:
type: string
description: >-
Identifier used to reference this format in API requests,
such as the file_format parameter on the uploads and
downloads endpoints.
example: yml
description:
type: string
description: Human-readable summary of the format and its typical use case.
example: YAML file format for use with Ruby/Rails applications
extension:
type: string
description: Default file extension associated with this format.
example: yml
default_encoding:
type: string
description: Default character encoding used when reading or writing files in this format.
example: UTF-8
importable:
type: boolean
description: Whether locale files can be imported using this format.
example: true
exportable:
type: boolean
description: Whether locale files can be exported using this format.
example: true
default_file:
type: string
description: >-
Conventional file path pattern for this format. Contains
locale_name as a placeholder for the locale identifier.
example: "./config/locales/<locale_name>.yml"
renders_default_locale:
type: boolean
description: >-
When true, exported files contain the default locale's content
for any key that has no translation in the target locale.
example: false
includes_locale_information:
type: boolean
description: >-
When true, files in this format embed locale information so
Phrase can detect the locale automatically on import.
example: false
example:
name: Ruby/Rails YAML
api_name: yml
Expand All @@ -33,4 +73,4 @@ format:
exportable: true
default_file: "./config/locales/<locale_name>.yml"
renders_default_locale: false
includes_locale_information: true
includes_locale_information: false
Loading