From d0f0bdfa7d119d091e0951f2eda5a1a8ab72a411 Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Mon, 17 Apr 2023 13:08:18 +0200 Subject: [PATCH] feat(developer): Document translation API Signed-off-by: Joas Schilling --- developer_manual/client_apis/OCS/index.rst | 1 + .../client_apis/OCS/ocs-translation-api.rst | 81 +++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 developer_manual/client_apis/OCS/ocs-translation-api.rst diff --git a/developer_manual/client_apis/OCS/index.rst b/developer_manual/client_apis/OCS/index.rst index 710d23e2802..00d7136b50a 100644 --- a/developer_manual/client_apis/OCS/index.rst +++ b/developer_manual/client_apis/OCS/index.rst @@ -12,3 +12,4 @@ OCS API ocs-status-api ocs-recommendations-api ocs-user-preferences-api + ocs-translation-api diff --git a/developer_manual/client_apis/OCS/ocs-translation-api.rst b/developer_manual/client_apis/OCS/ocs-translation-api.rst new file mode 100644 index 00000000000..fa9a6d3d8bf --- /dev/null +++ b/developer_manual/client_apis/OCS/ocs-translation-api.rst @@ -0,0 +1,81 @@ +=================== +OCS Translation API +=================== + +.. versionadded:: 26 + +The OCS Translation API allows you to translate strings from a language to another. + +The base URL for all calls to the share API is: */ocs/v2.php/translation/* + +All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``. + + +Get available translation options +--------------------------------- + +.. versionadded:: 26 + +* Method: ``GET`` +* Endpoint: ``/languages`` +* Response: + - Status code: + + ``200 OK`` + - Data: + ++----------------------+--------+---------------------------------------------------------------------------------------------------+ +| field | type | Description | ++----------------------+--------+---------------------------------------------------------------------------------------------------+ +|``languageDetection`` | bool | Whether "from" language can be skipped as a translation provider supports detecting it from input | ++----------------------+--------+---------------------------------------------------------------------------------------------------+ +|``languages`` | array | A list of language tuples, see definition below | ++----------------------+--------+---------------------------------------------------------------------------------------------------+ + +Language tuple structure +^^^^^^^^^^^^^^^^^^^^^^^^ + ++--------------+--------+--------------------------------------------------------------+ +| field | type | Description | ++--------------+--------+--------------------------------------------------------------+ +|``from`` | string | ISO code of the "from" language | ++--------------+--------+--------------------------------------------------------------+ +|``fromLabel`` | string | Name of the "from" language that should be shown to the user | ++--------------+--------+--------------------------------------------------------------+ +|``to`` | string | ISO code of the "to" language | ++--------------+--------+--------------------------------------------------------------+ +|``toLabel`` | string | Name of the "to" language that should be shown to the user | ++--------------+--------+--------------------------------------------------------------+ + +Translate a string +------------------ + +.. versionadded:: 26 + +.. note:: The endpoint is rate limited as it can be quite resource intensive. Users can make 25 requests in 2 minutes, guests only 10 + +* Method: ``POST`` +* Endpoint: ``/translate`` +* Data: + ++-----------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| field | type | Description | ++-----------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|``text`` | string | The text to be translated | ++-----------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|``fromLanguage`` | string/null | The ISO code of the "from" language, when null is given and a translation provider allows detecting the source language it will be tried to guess it from the ``text`` input | ++-----------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +|``toLanguage`` | string | The ISO code of the "to" language | ++-----------------+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +* Response: + - Status code: + + ``200 OK`` + + ``400 Bad Request`` - When the to language is not supported by any provider + + ``400 Bad Request`` - When the from language is not supported by any provider + + ``400 Bad Request`` - When the from language is not given, but no provider supports detecting the language + + ``412 Precondition Failed`` - When no translation provider is installed + + ``429 Too Many Requests`` - When the rate limiting was exceeded + + - Data: + + ``text`` - Only provided in case of ``200 OK``, the translated string + + ``message`` - Only provided when not ``200 OK``, an error message in the user's language, ready to be displayed