khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-02 17:59:36 +07:00
Code Issues Packages Projects Releases Wiki Activity

feat(developer): Document translation API

Browse Source 
Signed-off-by: Joas Schilling <coding@schilljs.com>
This commit is contained in:
Joas Schilling
2023-04-17 13:08:18 +02:00
parent 476c32c356
commit cd12c3ca92
2 changed files with 82 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
developer_manual/client_apis/OCS/index.rst
View File

@@ -12,3 +12,4 @@ OCS API
ocs-status-api
ocs-recommendations-api
ocs-user-preferences-api
ocs-translation-api

81
developer_manual/client_apis/OCS/ocs-translation-api.rst Normal file
View File

@@ -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: *<nextcloud_base_url>/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