add: status/translate

archetypes/entities.md

@@ -4,6 +4,10 @@ description:
 menu:
   docs:
     parent: entities
+aliases: [
+  "/api/entities/SOMETHING",
+  "/api/entities/something",
+]
 ---
 
 ## Example

archetypes/methods.md

@@ -4,6 +4,10 @@ description:
 menu:
   docs:
     parent: methods
+aliases: [
+  "/api/methods/SOMETHING",
+  "/api/methods/something",
+]
 ---
 
 ## What the method does {#anchor}

content/en/entities/Translation.md

@@ -0,0 +1,50 @@
+---
+title: Translation
+description: Represents the result of machine translating some status content
+menu:
+  docs:
+    parent: entities
+aliases: [
+  "/api/entities/Translation",
+  "/api/entities/translation",
+]
+---
+
+## Example
+
+```json
+{
+  "content": "<p>Hola mundo</p>",
+  "detected_source_language": "en",
+  "provider": "DeepL.com"
+}
+```
+
+## Attributes
+
+### `content` {#content}
+
+**Description:** The translated text of the status.\
+**Type:** String (HTML)\
+**Version history:**\
+4.0.0 - added
+
+### `detected_source_language` {#detected_source_language}
+
+**Description:** The language of the source text, as auto-detected by the machine translation provider.\
+**Type:** String (ISO 639 language code)\
+**Version history:**\
+4.0.0 - added
+
+### `provider` {#provider}
+
+**Description:** The service that provided the machine translation.
+**Type:** String\
+**Version history:**\
+4.0.0 - added
+
+## See also
+
+{{< page-relref ref="methods/statuses#translate" caption="POST /api/v1/statuses/:id/translate" >}}
+
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/serializers/rest/translation_serializer.rb" caption="app/serializers/rest/translation_serializer.rb" >}}

content/en/methods/statuses.md

@@ -523,6 +523,71 @@ Status is private or does not exist
 
 ---
 
+## Translate a status {#translate}
+
+```http
+POST /api/v1/statuses/:id/translate HTTP/1.1
+```
+
+Translate the status content into some language.
+
+**Returns:** [Translation]({{< relref "entities/translation" >}})\
+**OAuth:** App token + `read:statuses`\
+**Version history:**\
+4.0.0 - added
+
+#### Request
+
+##### Path parameters
+
+:id
+: {{<required>}} String. The ID of the Status in the database.
+
+##### Form data parameters
+
+lang
+: String (ISO 639 language code). The status content will be translated into this language. Defaults to the user's current locale.
+
+##### Headers
+
+Authorization
+: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
+
+#### Response
+##### 200: OK
+
+Translating the first "Hello world" post from mastodon.social into Spanish
+
+```json
+{
+  "content": "<p>Hola mundo</p>",
+  "detected_source_language": "en",
+  "provider": "DeepL.com"
+}
+```
+
+##### 404: Not found
+
+Status is private or does not exist
+
+```json
+{
+  "error": "Record not found"
+}
+```
+
+##### 503: Service unavailable
+
+The translation request failed
+
+```json
+{
+  "error": "Service Unavailable"
+}
+```
+
+---
+
 ## See who boosted a status {#reblogged_by}
 
 ```http