diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6f3f9413edab..d643732e1999 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -21,18 +21,40 @@ permissions: contents: read jobs: - update-snippets: + update-autogenerated-docs: runs-on: ubuntu-24.04 permissions: contents: write env: CI_REDIS_HOST: 127.0.0.1 - CI_REDIS_PORT: '60001' + CI_REDIS_PORT: '6379' CI_DB_PASSWORD: weblate CI_DB_HOST: 127.0.0.1 - CI_DB_PORT: '60000' + CI_DB_PORT: '5432' CI_SELENIUM: '1' DJANGO_SETTINGS_MODULE: weblate.settings_test + services: + database: + image: postgres:18.3-alpine@sha256:4da1a4828be12604092fa55311276f08f9224a74a62dcb4708bd7439e2a03911 + env: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: weblate + ports: + - 5432:5432 + options: >- + --health-cmd pg_isready + --health-interval 10s + --health-timeout 5s + --health-retries 5 + cache: + image: valkey/valkey:9.0.3-alpine@sha256:84c96f47ebe197e635cd3ddbe3ab74e8bdf783cf3befbfb1c36387275c1cd5d5 + ports: + - 6379:6379 + options: >- + --health-cmd "redis-cli ping" + --health-interval 10s + --health-timeout 5s + --health-retries 5 steps: - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 if: github.event_name != 'pull_request' && github.repository_owner == 'WeblateOrg' @@ -59,7 +81,11 @@ jobs: run: sudo ./ci/apt-install - name: Install Python dependencies run: ./ci/pip-install latest - - run: make -C docs update-doc-snippets + - name: Prepare database + run: ./ci/prepare-database + - name: Migrate database + run: uv run --frozen ./manage.py migrate --noinput --traceback + - run: make -C docs update-docs - name: Commit or create pull request uses: ./.github/actions/auto-commit @@ -73,7 +99,7 @@ jobs: list-languages: runs-on: ubuntu-24.04 needs: - - update-snippets + - update-autogenerated-docs outputs: languages: ${{ steps.list.outputs.languages }} steps: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0e73f82b910a..a0dc044ce81f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -111,7 +111,7 @@ repos: types: [rst] entry: \S +(?![\| +]) language: pygrep - exclude: docs/devel/reporting-example.rst|docs/admin/addons.rst|docs/snippets/file-format-parameters.rst + exclude: docs/devel/reporting-example.rst|docs/admin/addons.rst|docs/snippets/file-format-parameters.rst|docs/snippets/addons-autogenerated.rst - id: rst-http name: http link in rst text description: Detect mistake of using http links diff --git a/docs/Makefile b/docs/Makefile index 2404954f075d..c7bb99c52669 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -42,11 +42,14 @@ update-schemas: update-openapi: @WEBLATE_HIDE_VERSION=1 uv run --no-sync ../manage.py spectacular --skip-checks --fail-on-warn --validate > specs/openapi.yaml -update-doc-snippets: +update-docs: + @uv run --no-sync ../manage.py list_addons -o snippets/addons-autogenerated.rst + @uv run --no-sync ../manage.py list_machinery -o snippets/machines-autogenerated.rst @uv run --no-sync ../manage.py list_file_format_params > snippets/file-format-parameters.rst @uv run --no-sync ../manage.py list_permissions --sections perms > snippets/permissions.rst @uv run --no-sync ../manage.py list_permissions --sections roles > snippets/roles.rst - @uv run --no-sync ../manage.py list_change_events > snippets/change-events.rst + @uv run --no-sync ../manage.py list_checks -s checks -o snippets/checks-autogenerated.rst + @uv run --no-sync ../manage.py list_checks -s flags -o snippets/check-flags-autogenerated.rst update-po: $(wildcard locales/*/LC_MESSAGES/docs.po) diff --git a/docs/admin/addons.rst b/docs/admin/addons.rst index 774eaf79deb9..8daaf17ce396 100644 --- a/docs/admin/addons.rst +++ b/docs/admin/addons.rst @@ -17,1505 +17,7 @@ translation project or component. Add-ons can be also installed site-wide in :re .. image:: /screenshots/addons.webp -Events that trigger add-ons -+++++++++++++++++++++++++++ - -.. _addon-event-add-on-installation: - -Add-on installation -------------------- - -Triggered when add-on is being installed. - -.. _addon-event-component-update: - -Component update ----------------- - -Triggered whenever a change happens in a component such as: - -* Strings are changed in the repository. -* A string is added. -* A new translation is added. - -.. _addon-event-daily: - -Daily ------ - -Triggered daily, but add-ons usually split the daily load between components depending on :setting:`BACKGROUND_TASKS`. - -.. _addon-event-event-change: - -Event change ------------- - -Triggered after a Change event is created. - -.. _addon-event-repository-post-add: - -Repository post-add -------------------- - -Triggered just after the new translation is added and committed. - -.. _addon-event-repository-post-commit: - -Repository post-commit ----------------------- - -Triggered just after the changes are committed. - - -.. _addon-event-repository-post-push: - -Repository post-push --------------------- - -Triggered just after the repository is pushed upstream. - -.. _addon-event-repository-post-update: - -Repository post-update ----------------------- - -Triggered whenever new changes are pulled from the upstream repository. - -.. _addon-event-repository-pre-commit: - -Repository pre-commit ---------------------- - -Triggered just before the changes are committed. - -.. _addon-event-repository-pre-push: - -Repository pre-push -------------------- - -Triggered just before the repository is pushed upstream. - -.. _addon-event-repository-pre-update: - -Repository pre-update ---------------------- - -Triggered just before the repository update is attempted. - -.. _addon-event-unit-post-save: - -Unit post-save --------------- - -Triggered just after the string is saved. - -.. _addon-event-unit-post-sync: - -Unit post-sync --------------- - -Triggered after the string is synchronized with the VCS. - -.. _addon-event-unit-pre-create: - -Unit pre-create ---------------- - -Triggered just after the newly created string is saved. - - - - -Built-in add-ons -++++++++++++++++ - - -.. _addon-weblate.autotranslate.autotranslate: - -Automatic translation ---------------------- - -:Add-on ID: ``weblate.autotranslate.autotranslate`` -:Configuration: +-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+ - | ``mode`` | Automatic translation mode | .. list-table:: Available choices: | - | | | :width: 100% | - | | | | - | | | * - ``suggest`` | - | | | - Add as suggestion | - | | | * - ``translate`` | - | | | - Add as translation | - | | | * - ``fuzzy`` | - | | | - Add as "Needing edit" | - +-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+ - | ``q`` | Query | Please note that translating all strings will discard all existing translations. | - +-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+ - | ``auto_source`` | Source of automated translations | .. list-table:: Available choices: | - | | | :width: 100% | - | | | | - | | | * - ``others`` | - | | | - Other translation components | - | | | * - ``mt`` | - | | | - Machine translation | - +-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+ - | ``component`` | Component | Enter slug of a component to use as source, keep blank to use all components in the current project. | - +-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+ - | ``engines`` | Machine translation engines | :ref:`addon-choice-engines` | - +-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+ - | ``threshold`` | Score threshold | | - +-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+ -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update`, :ref:`addon-event-daily`, :ref:`addon-event-event-change` - -Automatically translates strings using machine translation or other components. - -.. seealso:: - - * :ref:`auto-translation` - * :ref:`translation-consistency` - * :ref:`mt-translation-services-priority` - * :ref:`search-strings` - -.. _addon-weblate.cdn.cdnjs: - -JavaScript localization CDN ---------------------------- - -.. versionadded:: 4.2 - -:Add-on ID: ``weblate.cdn.cdnjs`` -:Configuration: +------------------+---------------------------------+-------------------------------------------------------------------------------------------+ - | ``threshold`` | Translation threshold | The percentage of translated strings that must be present for translation to be included. | - +------------------+---------------------------------+-------------------------------------------------------------------------------------------+ - | ``css_selector`` | CSS selector | CSS selector to detect localizable elements. | - +------------------+---------------------------------+-------------------------------------------------------------------------------------------+ - | ``cookie_name`` | Language cookie name | Name of cookie which stores language preference. | - +------------------+---------------------------------+-------------------------------------------------------------------------------------------+ - | ``files`` | Extract strings from HTML files | List of filenames in current repository or remote URLs to parse for translatable strings. | - +------------------+---------------------------------+-------------------------------------------------------------------------------------------+ -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily`, :ref:`addon-event-repository-post-commit`, :ref:`addon-event-repository-post-update` - -Publishes translations into content delivery network for use in JavaScript or -HTML localization. - -Can be used to localize static HTML pages, or -to load localization in the JavaScript code. - -Generates a unique URL for your component you can include in -HTML pages to localize them. See :ref:`weblate-cdn` for more details. - -.. note:: - - This add-on requires additional configuration on the Weblate server. - :setting:`LOCALIZE_CDN_PATH` configures where generated files will be - written (on a filesystem), and :setting:`LOCALIZE_CDN_URL` defines where - they will be served (URL). Serving of the files is not done by Weblate and - has to be set up externally (typically using a CDN service). - - This add-on is configured on :guilabel:`Hosted Weblate` and serves the files - via ``https://weblate-cdn.com/``. - -.. seealso:: - - * :ref:`cdn-addon-config` - * :ref:`weblate-cdn` - * :ref:`cdn-addon-extract` - * :ref:`cdn-addon-html` - -.. _addon-weblate.cleanup.blank: - -Remove blank strings --------------------- - -.. versionadded:: 4.4 - -:Add-on ID: ``weblate.cleanup.blank`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-commit`, :ref:`addon-event-repository-post-update` - -Removes strings without a translation from translation files. - -Use this to not have any empty strings in translation files (for -example if your localization library displays them as missing instead -of falling back to the source string). - -.. seealso:: - - :ref:`faq-cleanup` - -.. _addon-weblate.cleanup.generic: - -Cleanup translation files -------------------------- - -:Add-on ID: ``weblate.cleanup.generic`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-update`, :ref:`addon-event-repository-pre-commit` - -Update all translation files to match the monolingual base file. For most file -formats, this means removing stale translation keys no longer present in the -base file. - -For formats containing additional content besides translation strings (such as -:ref:`html`, :ref:`winrc`, or :ref:`odf`) this also brings the translation file -in sync with the base file. - -.. seealso:: - - :ref:`faq-cleanup` - -.. _addon-weblate.consistency.languages: - -Add missing languages ---------------------- - -:Add-on ID: ``weblate.consistency.languages`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily`, :ref:`addon-event-repository-post-add` - -Ensures a consistent set of languages is used for all components within a -project. - -.. note:: - - The components shared from other projects are not considered in this. - -Missing languages are checked once every 24 hours, and when new languages -are added in Weblate. - -Unlike most others, this add-on affects the whole project. - -.. hint:: - - Auto-translate the newly added strings with - :ref:`addon-weblate.autotranslate.autotranslate`. - -.. _addon-weblate.discovery.discovery: - -Component discovery -------------------- - -:Add-on ID: ``weblate.discovery.discovery`` -:Configuration: +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``match`` | Regular expression to match translation files against | | - +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``file_format`` | File format | :ref:`addon-choice-file_format` | - +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``name_template`` | Customize the component name | | - +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``base_file_template`` | Define the monolingual base filename | Leave empty for bilingual translation files. | - +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``new_base_template`` | Define the base file for new translations | Filename of file used for creating new translations. For gettext choose .pot file. | - +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``intermediate_template`` | Intermediate language file | Filename of intermediate translation file. In most cases this is a translation file provided by developers and is used when creating actual source strings. | - +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``language_regex`` | Language filter | Regular expression to filter translation files against when scanning for file mask. | - +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``copy_addons`` | Clone add-ons from the main component to the newly created ones | | - +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``remove`` | Remove components for inexistent files | | - +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``confirm`` | I confirm the above matches look correct | | - +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-update` - -Automatically adds or removes project components based on file changes in the -version control system. - -The matching is done using regular expressions -enabling complex configuration, but some knowledge is required to do so. -Some examples for common use cases can be found in -the add-on help section. - -The regular expression to match translation files has to contain two named -groups to match component and language. All named groups in the regular -expression can be used as variables in the template fields. - -You can use Django template markup in all filename fields, for example: - -``{{ component }}`` - Component filename match -``{{ component|title }}`` - Component filename with upper case first letter -``{{ path }}: {{ component }}`` - Custom match group from the regular expression - -Once you hit :guilabel:`Save`, a preview of matching components will be presented, -from where you can check whether the configuration actually matches your needs: - -.. image:: /screenshots/addon-discovery.webp - -Component discovery examples -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -One folder per language -####################### - -One folder per language containing translation files for components. - -Regular expression: - ``(?P[^/.]*)/(?P[^/]*)\.po`` -Matching files: - - :file:`cs/application.po` - - :file:`cs/website.po` - - :file:`de/application.po` - - :file:`de/website.po` - -Gettext locales layout -###################### - -Usual structure for storing gettext PO files. - -Regular expression: - ``locale/(?P[^/.]*)/LC_MESSAGES/(?P[^/]*)\.po`` -Matching files: - - :file:`locale/cs/LC_MESSAGES/application.po` - - :file:`locale/cs/LC_MESSAGES/website.po` - - :file:`locale/de/LC_MESSAGES/application.po` - - :file:`locale/de/LC_MESSAGES/website.po` - -Complex filenames -################# - -Using both component and language name within filename. - -Regular expression: - ``src/locale/(?P[^/]*)\.(?P[^/.]*)\.po`` -Matching files: - - :file:`src/locale/application.cs.po` - - :file:`src/locale/website.cs.po` - - :file:`src/locale/application.de.po` - - :file:`src/locale/website.de.po` - -Repeated language code -###################### - -Using language in both path and filename. - -Regular expression: - ``locale/(?P[^/.]*)/(?P[^/]*)/(?P=language)\.po`` -Matching files: - - :file:`locale/cs/application/cs.po` - - :file:`locale/cs/website/cs.po` - - :file:`locale/de/application/de.po` - - :file:`locale/de/website/de.po` - - -Split Android strings -##################### - -Android resource strings, split into several files. - -Regular expression: - ``res/values-(?P[^/.]*)/strings-(?P[^/]*)\.xml`` -Matching files: - - :file:`res/values-cs/strings-about.xml` - - :file:`res/values-cs/strings-help.xml` - - :file:`res/values-de/strings-about.xml` - - :file:`res/values-de/strings-help.xml` - -Matching multiple paths -####################### - -Multi-module Maven project with Java properties translations. - -Regular expression: - ``(?P.+/)(?P[^/]*)/src/main/resources/ApplicationResources_(?P[^/.]*)\.properties`` -Component name: - ``{{ originalHierarchy }}: {{ component }}`` -Matching files: - - :file:`parent/module1/submodule/src/main/resources/ApplicationResources_fr.properties` - - :file:`parent/module1/submodule/src/main/resources/ApplicationResource_es.properties` - - :file:`parent/module2/src/main/resources/ApplicationResource_de.properties` - - :file:`parent/module2/src/main/resources/ApplicationResource_ro.properties` - -Excluding certain matches -######################### - -Negative lookahead can be used to exclude certain patterns from being processed. - -Regular expression: - ``res/values-(?P[^/.]*)/strings-(?P(?!(about|info)[^/]*)\.xml`` -Matching files: - - :file:`res/values-cs/strings-help.xml` - - :file:`res/values-de/strings-help.xml` -Not matching files: - - :file:`res/values-cs/strings-about.xml` - - :file:`res/values-de/strings-about.xml` - - :file:`res/values-cs/strings-info-1.xml` - - :file:`res/values-de/strings-info-1.xml` - - :file:`res/values-cs/strings-info-2.xml` - - :file:`res/values-de/strings-info-2.xml` - - -.. hint:: - - Component discovery add-on uses :ref:`internal-urls`. It’s a convenient way to share - VCS setup between multiple components. Linked components use the local repository of - the main component set up by filling ``weblate://project/main-component`` - into the :ref:`component-repo` field (in :guilabel:`Operations` ↓ :guilabel:`Settings` ↓ - :guilabel:`Version control system`) of each respective component. - This saves time with configuration and system resources too. - -.. hint:: - - Ensure the new component contains the full set of translatable languages with - :ref:`addon-weblate.consistency.languages`. - -.. warning:: - - To be discovered, a new component must contain a file that matches ``base_file_template`` - **and** at least one file with a name that matches ``match`` -- i.e., the component must - contain a base language file and at least one existing translation. Otherwise, it will be - ignored. - -.. seealso:: - - * :ref:`markup` - * :wladmin:`import_project` - -.. _fedora-messaging: -.. _addon-weblate.fedora_messaging.publish: - -Fedora Messaging ----------------- - -.. versionadded:: 5.15 - -:Add-on ID: ``weblate.fedora_messaging.publish`` -:Configuration: +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ - | ``events`` | Change events | :ref:`addon-choice-events` | - +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ - | ``amqp_host`` | AMQP broker host | The AMQP broker to connect to. | - +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ - | ``amqp_ssl`` | Use SSL for AMQP connection | | - +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ - | ``ca_cert`` | CA certificates | Bundle of PEM encoded CA certificates used to validate the certificate presented by the server. | - +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ - | ``client_key`` | Client SSL key | PEM encoded client private SSL key. | - +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ - | ``client_cert`` | Client SSL certificates | PEM encoded client SSL certificate. | - +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ -:Triggers: :ref:`addon-event-event-change` - -Sends notifications to a Fedora Messaging compatible AMQP exchange. - -Fedora Messaging is AMQP-based publisher for all changes happening in Weblate. -You can hook additional services on changes happening in Weblate using this. - -Message topic -~~~~~~~~~~~~~ - -All messages have topic -``weblate....``. The action is -lowercase textual representation of action with underscores instead of space, -for example ``resource_update``, all other parts are optional and represent -slug of the object or a language code. - -Message body -~~~~~~~~~~~~ - -The body consists of following fields (given that they are available for the event): - -``change_id`` - Numerical ID of change -``action`` - Verbose name of the change. -``timestamp`` - ISO formatted timestamp -``target`` - New value of the change (eg. new translation of the string) -``old`` - Old value of the change (eg. previous translation of the string) -``source`` - Source string. -``url`` - Absolute URL to view the related object. -``author`` - Author username (this can be different from user for example when accepting suggestions) -``user`` - Acting username -``project`` - Project slug -``component`` - Component slug -``translation`` - Translation language code - -Message headers -~~~~~~~~~~~~~~~ - -There are additional headers which you might utilize for routing as well: - -``action`` - Verbose name of the change. -``project`` - Project slug -``component`` - Component slug - -Example messages -~~~~~~~~~~~~~~~~ - -Repository merge event: - -.. code-block:: json - - { - "id": 1, - "action": "Merged repository", - "timestamp": "2017-06-15T11:30:47.325000+00:00", - "url": "http://example.com/projects/test/test/", - "component": "test" - } - -New source string event: - -.. code-block:: json - - { - "id": 2, - "action": "New source string", - "timestamp": "2017-06-15T11:30:47.372000+00:00", - "url": "http://example.com/translate/test/test/cs/?checksum=6412684aaf018e8e", - "component": "test", - "translation": "cs", - "source": ["Hello, world!\n"] - } - -Resource update event: - -.. code-block:: json - - { - "id": 6, - "action": "Resource update", - "timestamp": "2017-06-15T11:30:47.410000+00:00", - "url": "http://example.com/projects/test/test/cs/", - "project": "test", - "component": "test", - "translation": "cs" - } - { - "id": 7, - "action": "Resource update", - "timestamp": "2017-06-15T11:30:47.510000+00:00", - "url": "http://example.com/projects/test/test/de/", - "project": "test", - "component": "test", - "translation": "de" - } - { - "id": 8, - "action": "Resource update", - "timestamp": "2017-06-15T11:30:47.595000+00:00", - "url": "http://example.com/projects/test/test/it/", - "project": "test", - "component": "test", - "translation": "it" - } - -Project removal event: - -.. code-block:: json - - { - "id": 9, - "action": "Removed project", - "timestamp": "2019-10-17T15:57:08.559420+00:00", - "target": "test", - "user": "testuser" - } - -New contributor event: - -.. code-block:: json - - { - "id": 11, - "action": "New contributor", - "timestamp": "2019-10-17T15:57:08.759960+00:00", - "url": "http://example.com/translate/test/test/cs/?checksum=6412684aaf018e8e", - "author": "testuser", - "user": "testuser", - "project": "test", - "component": "test", - "translation": "cs", - "source": ["Hello, world!\n"] - } - -New translation event: - -.. code-block:: json - - { - "id": 12, - "action": "New translation", - "timestamp": "2019-10-17T15:57:08.772591+00:00", - "url": "http://example.com/translate/test/test/cs/?checksum=6412684aaf018e8e", - "target": ["Ahoj svete!\n"], - "author": "testuser", - "user": "testuser", - "project": "test", - "component": "test", - "translation": "cs", - "source": ["Hello, world!\n"] - } - -.. seealso:: - - * `Configuring Fedora Messaging`_ - * :ref:`schema-messaging` - -.. _Configuring Fedora Messaging: https://fedora-messaging.readthedocs.io/en/stable/user-guide/configuration.html - -.. _addon-weblate.flags.bulk: - -Bulk edit ---------- - -:Add-on ID: ``weblate.flags.bulk`` -:Configuration: +-------------------+-----------------------------+----------------------------------------+ - | ``q`` | Query | | - +-------------------+-----------------------------+----------------------------------------+ - | ``state`` | State to set | .. list-table:: Available choices: | - | | | :width: 100% | - | | | | - | | | * - ``-1`` | - | | | - Do not change | - | | | * - ``10`` | - | | | - Needs editing | - | | | * - ``11`` | - | | | - Needs editing (Needs rewriting) | - | | | * - ``12`` | - | | | - Needs editing (Needs checking) | - | | | * - ``20`` | - | | | - Translated | - | | | * - ``30`` | - | | | - Approved | - +-------------------+-----------------------------+----------------------------------------+ - | ``add_flags`` | Translation flags to add | | - +-------------------+-----------------------------+----------------------------------------+ - | ``remove_flags`` | Translation flags to remove | | - +-------------------+-----------------------------+----------------------------------------+ - | ``add_labels`` | Labels to add | | - +-------------------+-----------------------------+----------------------------------------+ - | ``remove_labels`` | Labels to remove | | - +-------------------+-----------------------------+----------------------------------------+ -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update` - -Bulk edit flags, labels, or states of strings. - -**Examples:** - -.. list-table:: Label new strings automatically - :stub-columns: 1 - - * - Search query - - ``NOT has:label`` - * - Labels to add - - *recent* - -.. list-table:: Marking all :ref:`appstore` changelog strings read-only - :stub-columns: 1 - - * - Search query - - ``language:en AND key:changelogs/`` - * - Translation flags to add - - ``read-only`` - - -.. list-table:: Marking certain strings read-only - :stub-columns: 1 - - * - Search query - - ``source:r"^\`\`[.a-zA-Z0-9_-]*\`\`$" AND language:en`` - * - Translation flags to add - - ``read-only`` - -.. seealso:: - - * :ref:`bulk-edit` - * :ref:`custom-checks` - * :ref:`labels` - - -.. _addon-weblate.flags.same_edit: - -Flag unchanged translations as "Needs rewriting" ------------------------------------------------- - -:Add-on ID: ``weblate.flags.same_edit`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-unit-pre-create` - -Whenever a new translatable string is imported from the VCS and it matches a -source string, it is flagged as needing rewriting in Weblate. Especially useful -for file formats that include source strings for untranslated strings. - -.. hint:: - - You might also want to tighthen the :ref:`check-same` check by adding - ``strict-same`` flag to :ref:`component-check_flags`. - -.. seealso:: - - :ref:`states` - -.. _addon-weblate.flags.source_edit: - -Flag new source strings as "Needs checking" -------------------------------------------- - -:Add-on ID: ``weblate.flags.source_edit`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-unit-pre-create` - -Whenever a new source string is imported from the VCS, it is flagged as needing -checking in Weblate. This way you can easily filter and edit source strings -written by the developers. - -.. seealso:: - - :ref:`states` - -.. _addon-weblate.flags.target_edit: - -Flag new translations as "Needs rewriting" ------------------------------------------- - -:Add-on ID: ``weblate.flags.target_edit`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-unit-pre-create` - -Whenever a new translatable string is imported from the VCS, it is flagged as -needing rewriting in Weblate. This way you can easily filter and edit -translations created by the developers. - -.. seealso:: - - :ref:`states` - -.. _addon-weblate.flags.target_repo_update: - -Flag updated translations from repository as "Needs rewriting" --------------------------------------------------------------- - -:Add-on ID: ``weblate.flags.target_repo_update`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-unit-post-sync` - -Whenever a string translation is changed from the VCS, it is flagged as needing -rewriting in Weblate. Especially useful if translation files are often updated -manually or by an external service. - -.. seealso:: - - :ref:`states` - -.. _addon-weblate.generate.fill_read_only: - -Fill read-only strings with source ----------------------------------- - -.. versionadded:: 4.18 - -:Add-on ID: ``weblate.generate.fill_read_only`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update`, :ref:`addon-event-daily` - -Fills in translation of read-only strings with source string. - -.. _addon-weblate.generate.generate: - -Statistics generator --------------------- - -:Add-on ID: ``weblate.generate.generate`` -:Configuration: +--------------+---------------------------+--+ - | ``filename`` | Name of generated file | | - +--------------+---------------------------+--+ - | ``template`` | Content of generated file | | - +--------------+---------------------------+--+ -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-pre-commit` - -Generates a file containing detailed info about the translation status. - -You can use a Django template in both filename and content, see :ref:`markup` -for a detailed markup description. - -For example generating a summary file for each translation: - -Name of generated file - ``locale/{{ language_code }}.json`` -Content - .. code-block:: json - - { - "language": "{{ language_code }}", - "strings": "{{ stats.all }}", - "translated": "{{ stats.translated }}", - "last_changed": "{{ stats.last_changed }}", - "last_author": "{{ stats.last_author }}", - } - - -.. seealso:: - - :ref:`markup` - -.. _addon-weblate.generate.prefill: - -Prefill translation with source -------------------------------- - -.. versionadded:: 4.11 - -:Add-on ID: ``weblate.generate.prefill`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update`, :ref:`addon-event-daily` - -Fills in translation strings with source string. - -All untranslated strings in the component will be filled with the source -string, and marked as needing edit. Use this when you can not have empty -strings in the translation files. - -.. _addon-weblate.generate.pseudolocale: - -Pseudolocale generation ------------------------ - -.. versionadded:: 4.5 - -:Add-on ID: ``weblate.generate.pseudolocale`` -:Configuration: +----------------------+---------------------------+------------------------------------------------------------------------------------------+ - | ``source`` | Source strings | | - +----------------------+---------------------------+------------------------------------------------------------------------------------------+ - | ``target`` | Target translation | All strings in this translation will be overwritten | - +----------------------+---------------------------+------------------------------------------------------------------------------------------+ - | ``prefix`` | Prepended static text | | - +----------------------+---------------------------+------------------------------------------------------------------------------------------+ - | ``var_prefix`` | Prepended variable text | | - +----------------------+---------------------------+------------------------------------------------------------------------------------------+ - | ``suffix`` | Appended static text | | - +----------------------+---------------------------+------------------------------------------------------------------------------------------+ - | ``var_suffix`` | Appended variable text | | - +----------------------+---------------------------+------------------------------------------------------------------------------------------+ - | ``var_multiplier`` | Variable text multiplier | How many times to repeat the variable text depending on the length of the source string. | - +----------------------+---------------------------+------------------------------------------------------------------------------------------+ - | ``include_readonly`` | Include read-only strings | | - +----------------------+---------------------------+------------------------------------------------------------------------------------------+ -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update`, :ref:`addon-event-daily` - -Generates a translation by adding prefix and suffix to source strings -automatically. - -Pseudolocales are useful to find strings that are not prepared for -localization. This is done by altering all translatable source strings -to make it easy to spot unaltered strings when running the application -in the pseudolocale language. - -Finding strings whose localized counterparts might not fit the layout -is also possible. - -Using the variable parts makes it possible to look for strings which might not -fit into the user interface after the localization - it extends the text based -on the source string length. The variable texts are repeated by length of the -text multiplied by the multiplier. For example ``Hello world`` with variable -text ``_`` and variable multiplier of 1 becomes ``Hello world___________`` - -the text is repeated once for each character in the source string. - -The strings will be generated using following pattern: - -:guilabel:`Prepended static text` -:guilabel:`Prepended variable text` -:guilabel:`Source string` -:guilabel:`Appended variable text` -:guilabel:`Appended static text` - -.. hint:: - - You can use real languages for testing, but there are dedicated - pseudolocales available in Weblate - `en_XA` and `ar_XB`. - -.. hint:: - - You can use this add-on to start translation to a new locale of an - existing language or similar language. - Once you add the translation to the component, follow to the add-on. - *Example:* If you have `fr` and want to start `fr_CA` translation, simply set - `fr` as the source, `fr_CA` as the target, and leave the prefix and suffix blank. - - Uninstall the add-on once you have the new translation filled to prevent Weblate - from changing the translations made after the copying. - - -.. _addon-weblate.gettext.authors: - -Contributors in comment ------------------------ - -:Add-on ID: ``weblate.gettext.authors`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-repository-pre-commit` - -Updates the comment part of the PO file header to include contributor names and -years of contributions. - -The PO file header will look like this: - -.. code-block:: po - - # Michal Čihař , 2012, 2018, 2019, 2020. - # Pavel Borecki , 2018, 2019. - # Filip Hron , 2018, 2019. - # anonymous , 2019. - -.. _addon-weblate.gettext.configure: - -Update ALL_LINGUAS variable in the "configure" file ---------------------------------------------------- - -:Add-on ID: ``weblate.gettext.configure`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily`, :ref:`addon-event-repository-post-add` - -Updates the ALL_LINGUAS variable in :file:`configure`, :file:`configure.in` or any -:file:`configure.ac` files, when a new translation is added. - -.. _addon-weblate.gettext.customize: - -Customize gettext output ------------------------- - -.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`. - -.. _addon-weblate.gettext.linguas: - -Update LINGUAS file -------------------- - -:Add-on ID: ``weblate.gettext.linguas`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily`, :ref:`addon-event-repository-post-add` - -Updates the LINGUAS file when a new translation is added. - -.. _addon-weblate.gettext.mo: - -Generate MO files ------------------ - -:Add-on ID: ``weblate.gettext.mo`` -:Configuration: +-----------+---------------------------------+----------------------------------------------------------------------------------+ - | ``path`` | Path of generated MO file | If not specified, the location of the PO file will be used. | - +-----------+---------------------------------+----------------------------------------------------------------------------------+ - | ``fuzzy`` | Include strings needing editing | Strings needing editing (fuzzy) are typically not ready for use as translations. | - +-----------+---------------------------------+----------------------------------------------------------------------------------+ -:Triggers: :ref:`addon-event-repository-pre-commit` - -Automatically generates a MO file for every changed PO file. - -The location of the generated MO file can be customized and the field for it uses :ref:`markup`. - -.. note:: - - If a translation is removed, its PO file will be deleted from the - repository, but the MO file generated by this add-on will not. The MO file - must be removed from the upstream manually. - - -.. _addon-weblate.gettext.msgmerge: - -Update PO files to match POT (msgmerge) ---------------------------------------- - -.. versionchanged:: 5.13 - - :guilabel:`Settings` configuration has been moved to :ref:`file_format_params`. - -:Add-on ID: ``weblate.gettext.msgmerge`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-update` - -Updates all PO files (as configured by :ref:`component-filemask`) to match the -POT file (as configured by :ref:`component-new_base`) using :program:`msgmerge`. - -This add-on is essential when working with gettext PO files where the POT -(template) file is updated with new strings or changes to existing strings. -When the POT file is updated in the repository, this add-on automatically -merges those changes into all language PO files, ensuring that: - -* New translatable strings appear in all languages -* Removed strings are marked as obsolete -* Modified strings are marked as needing review (fuzzy) - -Most msgmerge command-line options can be set up through file format parameters -configuration. - -.. seealso:: - - * :ref:`faq-cleanup` - * :ref:`updating-target-files` - -.. _addon-weblate.git.squash: - -Squash Git commits ------------------- - -:Add-on ID: ``weblate.git.squash`` -:Configuration: +---------------------+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``squash`` | Commit squashing | .. list-table:: Available choices: | - | | | :width: 100% | - | | | | - | | | * - ``all`` | - | | | - All commits into one | - | | | * - ``language`` | - | | | - Per language | - | | | * - ``file`` | - | | | - Per file | - | | | * - ``author`` | - | | | - Per author | - +---------------------+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``append_trailers`` | Append trailers to squashed commit message | Trailer lines are lines that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit message, such as 'Co-authored-by: …'. | - +---------------------+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``commit_message`` | Commit message | This commit message will be used instead of the combined commit messages from the squashed commits. | - +---------------------+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-commit` - -Squash Git commits prior to pushing changes. - -.. hint:: - - To avoid unnecessary conflicts, it is recommended to configure automatic - receiving of upstream changes by webhooks or API, see :ref:`update-vcs`. - -Git commits can be squashed prior to pushing changes -in one of the following modes: - -* All commits into one -* Per language -* Per file -* Per author - -Original commit messages are kept, but authorship is lost unless :guilabel:`Per author` is selected, or -the commit message is customized to include it. - -The original commit messages can optionally be overridden with a custom commit message. - -Trailers (commit lines like ``Co-authored-by: …``) can optionally be removed -from the original commit messages and appended to the end of the squashed -commit message. This also generates proper ``Co-authored-by:`` credit for every -translator. - -.. _addon-weblate.json.customize: - -Customize JSON output ---------------------- - -.. versionchanged:: 5.12 - - :guilabel:`Avoid spaces after separators` option added. - -.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`. - -.. _addon-weblate.properties.sort: - -Format the Java properties file -------------------------------- - -:Add-on ID: ``weblate.properties.sort`` -:Configuration: +--------------------+-----------------------------------+--+ - | ``case_sensitive`` | Enable case-sensitive key sorting | | - +--------------------+-----------------------------------+--+ -:Triggers: :ref:`addon-event-repository-pre-commit` - -Formats and sorts the Java properties file. - -* Consolidates newlines to Unix ones. -* Uppercase formatting of Unicode escape sequences (in case they are present). -* Strips blank lines and comments. -* Sorts the strings by the keys. -* Drops duplicate strings. - -.. _addon-weblate.removal.comments: - -Stale comment removal ---------------------- - -:Add-on ID: ``weblate.removal.comments`` -:Configuration: +---------+--------------+--+ - | ``age`` | Days to keep | | - +---------+--------------+--+ -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily` - -Set a timeframe for removal of comments. - -This can be useful to remove old -comments which might have become outdated. Use with care as comments -getting old does not mean they have lost their importance. - -.. _addon-weblate.removal.suggestions: - -Stale suggestion removal ------------------------- - -:Add-on ID: ``weblate.removal.suggestions`` -:Configuration: +-----------+------------------+-------------------------------------------------------------------------+ - | ``age`` | Days to keep | | - +-----------+------------------+-------------------------------------------------------------------------+ - | ``votes`` | Voting threshold | Threshold for removal. This field has no effect with voting turned off. | - +-----------+------------------+-------------------------------------------------------------------------+ -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily` - -Set a timeframe for removal of suggestions. - -Can be very useful in connection with suggestion voting -(see :ref:`peer-review`) to remove suggestions which -don't receive enough positive votes in a given timeframe. - -.. _addon-weblate.resx.update: - -Update RESX files ------------------ - -:Add-on ID: ``weblate.resx.update`` -:Configuration: `This add-on has no configuration.` -:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-update` - -Update all translation files to match the monolingual upstream base file. -Unused strings are removed, and new ones added as copies of the source string. - -.. hint:: - - Use :ref:`addon-weblate.cleanup.generic` if you only want to remove stale - translation keys. - -.. seealso:: - - :ref:`faq-cleanup` - -.. _addon-weblate.webhook.slack: - -Slack Webhooks --------------- - -.. versionadded:: 5.12 - -:Add-on ID: ``weblate.webhook.slack`` -:Configuration: +-----------------+---------------+----------------------------+ - | ``webhook_url`` | Webhook URL | | - +-----------------+---------------+----------------------------+ - | ``events`` | Change events | :ref:`addon-choice-events` | - +-----------------+---------------+----------------------------+ -:Triggers: :ref:`addon-event-event-change` - -Sends notification to a Slack channel based on selected events. - -.. warning:: - - The notification content might show HTML tags. This is a known issue that will be soon addressed; see https://github.com/WeblateOrg/weblate/issues/15056. - -.. hint:: - - To obtain a webhook URL, follow the steps outlined in the `Slack Incoming Webhooks documentation `_ - -.. _addon-weblate.webhook.webhook: - -Webhook -------- - -.. versionadded:: 5.11 - -.. versionchanged:: 5.15 - - Compliance of the secret length with the specification is now validated. - -:Add-on ID: ``weblate.webhook.webhook`` -:Configuration: +-----------------+----------------+----------------------------------------------------------+ - | ``webhook_url`` | Webhook URL | | - +-----------------+----------------+----------------------------------------------------------+ - | ``secret`` | Webhook secret | The Standard Webhooks secret is a base64 encoded string. | - +-----------------+----------------+----------------------------------------------------------+ - | ``events`` | Change events | :ref:`addon-choice-events` | - +-----------------+----------------+----------------------------------------------------------+ -:Triggers: :ref:`addon-event-event-change` - -Sends notifications to external services based on selected events, following -the Standard Webhooks specification. - -The request payload complies with the :ref:`schema-messaging` schema. -The OpenAPI description can also be found at ``/api/docs/``. -Sample request body: - -.. code-block:: json - - { - "change_id": 99, - "action": "Translation changed", - "timestamp": "2019-08-24T14:15:22Z", - "target": "Nazdar svete!", - "old": "Nazdar!", - "source": "Hello, world", - "url": "/translate/project-slug/component-slug/cs/?checksum=46add148a53cab6f", - "author": "author-username", - "user": "user-username", - "project": "project-slug", - "component": "component-slug", - "translation": "cs" - } - -Sample request body with categories: - -.. code-block:: json - - { - "change_id": 8910, - "action": "Component renamed", - "timestamp": "2025-06-11T07:15:09Z", - "target": ["new-name"], - "old": ["component-slug"], - "url": "/projects/project-slug/parent-category/child-category/sub-category/component-slug/", - "user": "testuser", - "project": "project-slug", - "component": "component-slug", - "category": [ - "sub-category", - "child-category", - "parent-category" - ] - } - -Sample request headers: - -.. code-block:: properties - - webhook-id: 7f1c5477f6275a69af7b83236c20cb1a - webhook-timestamp: 1748505623.044281 - webhook-signature: v1,Ceo5qEr07ixe2NLpvHk3FH9bwy/WavXrAFQ/9tdO6mc= - -The ``webhook-signature`` is a space separated list of HMAC signatures generated using the ``secret`` string, -the request payload, the ``webhook-timestamp``, and the ``webhook-id``. This ensures the authenticity -and integrity of the webhook request. - -The provided ``secret`` is a base64 encoded string between 24 bytes (192 bits) -and 64 bytes (512 bits). It can be prefixed with ``whsec_`` for easy -identification. - -To verify a request, you can use the ``Webhook.verify`` method from the ``standardwebhooks`` library -or an implementation of the "Standard Webhooks Specification". - - -.. seealso:: - - * `Standard Webhooks Specification `_ - * :ref:`schema-messaging` - * `Python library for Standard Webhooks `_ - - - -.. _addon-weblate.xml.customize: - -Customize XML output --------------------- - -.. versionadded:: 4.15 - -.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`. - -.. _addon-weblate.yaml.customize: - -Customize YAML output ---------------------- - -.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`. - -Common add-on parameters -++++++++++++++++++++++++ - -.. _addon-choice-engines: - -Machine translation engines ---------------------------- - -.. list-table:: Available choices: - :width: 100% - - * - ``aws`` - - Amazon Translate - * - ``deepl`` - - DeepL - * - ``google-translate-api-v3`` - - Google Cloud Translation Advanced - * - ``google-translate`` - - Google Cloud Translation Basic - * - ``microsoft-translator`` - - Azure AI Translator - * - ``modernmt`` - - ModernMT - * - ``openai`` - - OpenAI - * - ``weblate`` - - Weblate - * - ``weblate-translation-memory`` - - Weblate Translation Memory - -.. _addon-choice-events: - -Change events -------------- - -.. include:: /snippets/change-events.rst - -.. _addon-choice-file_format: - -File format ------------ - -.. list-table:: Available choices: - :width: 100% - - * - ``appstore`` - - App store metadata files - * - ``arb`` - - ARB file - * - ``aresource`` - - Android String Resource - * - ``ass`` - - Advanced SubStation Alpha subtitle file - * - ``catkeys`` - - Haiku catkeys - * - ``cmp-resource`` - - Compose Multiplatform Resource - * - ``csv`` - - CSV file - * - ``csv-multi-utf-8`` - - Multivalue CSV file (UTF-8) - * - ``csv-simple`` - - Simple CSV file - * - ``csv-simple-iso`` - - Simple CSV file (ISO-8859-1) - * - ``csv-simple-utf-8`` - - Simple CSV file (UTF-8) - * - ``csv-utf-8`` - - CSV file (UTF-8) - * - ``dokuwiki`` - - DokuWiki text file - * - ``dtd`` - - DTD file - * - ``flatxml`` - - Flat XML file - * - ``fluent`` - - Fluent file - * - ``formatjs`` - - Format.JS JSON file - * - ``go-i18n-json`` - - go-i18n v1 JSON file - * - ``go-i18n-json-v2`` - - go-i18n v2 JSON file - * - ``go-i18n-toml`` - - go-i18n TOML file - * - ``gotext`` - - gotext JSON file - * - ``gwt`` - - GWT properties (UTF-8) - * - ``gwt-iso`` - - GWT properties (ISO-8859-1) - * - ``html`` - - HTML file - * - ``i18next`` - - i18next JSON file v3 - * - ``i18nextv4`` - - i18next JSON file v4 - * - ``idml`` - - IDML file - * - ``ini`` - - INI file - * - ``islu`` - - Inno Setup INI file - * - ``joomla`` - - Joomla language file - * - ``json`` - - JSON file - * - ``json-nested`` - - JSON nested structure file - * - ``laravel`` - - Laravel PHP strings - * - ``markdown`` - - Markdown file - * - ``mediawiki`` - - MediaWiki text file - * - ``mi18n-lang`` - - @draggable/i18n lang file - * - ``moko-resource`` - - Mobile Kotlin Resource - * - ``nextcloud-json`` - - Nextcloud JSON file - * - ``odf`` - - OpenDocument file - * - ``php`` - - PHP strings - * - ``plainxliff`` - - XLIFF 1.2 translation file - * - ``po`` - - gettext PO file - * - ``po-mono`` - - gettext PO file (monolingual) - * - ``poxliff`` - - XLIFF 1.2 with gettext extensions - * - ``properties`` - - Java Properties (ISO 8859-1) - * - ``properties-utf16`` - - Java Properties (UTF-16) - * - ``properties-utf8`` - - Java Properties (UTF-8) - * - ``rc`` - - RC file - * - ``resjson`` - - RESJSON file - * - ``resourcedictionary`` - - ResourceDictionary file - * - ``resx`` - - .NET resource file - * - ``ruby-yaml`` - - Ruby YAML file - * - ``srt`` - - SubRip subtitle file - * - ``ssa`` - - SubStation Alpha subtitle file - * - ``strings`` - - iOS strings (UTF-16) - * - ``strings-utf8`` - - iOS strings (UTF-8) - * - ``stringsdict`` - - Stringsdict file - * - ``sub`` - - MicroDVD subtitle file - * - ``tbx`` - - TermBase eXchange file - * - ``toml`` - - TOML file - * - ``ts`` - - Qt Linguist translation file - * - ``txt`` - - Plain text file - * - ``webextension`` - - WebExtension JSON file - * - ``xliff`` - - XLIFF 1.2 with placeables support - * - ``xliff2`` - - XLIFF 2.0 translation file - * - ``xliff2-placeables`` - - XLIFF 2.0 translation file with placeables support - * - ``xlsx`` - - Excel Open XML - * - ``xwiki-fullpage`` - - XWiki Full Page - * - ``xwiki-java-properties`` - - XWiki Java Properties - * - ``xwiki-page-properties`` - - XWiki Page Properties - * - ``yaml`` - - YAML file +.. include:: /snippets/addons-autogenerated.rst Customizing list of add-ons diff --git a/docs/admin/checks.rst b/docs/admin/checks.rst index 0c3bf8742db9..b20dfcbd2fce 100644 --- a/docs/admin/checks.rst +++ b/docs/admin/checks.rst @@ -77,272 +77,7 @@ for this particular string. Here is a list of flags currently accepted: -``rst-text`` - Treat a text as an reStructuredText document, affects :ref:`check-same`. - Turns on :ref:`check-rst-syntax` and :ref:`check-rst-references`. -``bbcode-text`` - Treat a text as an Bulletin Board Code (BBCode) document, affects :ref:`check-same`. -``dos-eol`` - Uses DOS end-of-line markers instead of Unix ones (``\r\n`` instead of ``\n``). -``read-only`` - The string is read-only and should not be edited in Weblate, see :ref:`read-only-strings`. -``terminology`` - Used in :ref:`glossary`. Copies the string into all glossary languages so it can be used consistently in all translations. Also useful in combination with ``read-only``, for example in product names. -``priority:N`` - Priority of the string. Higher priority strings are presented first for translation. - The default priority is 100, the higher priority a string has, the earlier it is - offered for translation. -``max-length:N`` - Limit the maximal length for a string to N characters, see :ref:`check-max-length`. -``xml-text`` - Treat text as XML document, affects :ref:`check-xml-invalid` and :ref:`check-xml-tags`. -``font-family:NAME`` - Define font-family for rendering checks, see :ref:`fonts`. -``font-weight:WEIGHT`` - Define font-weight for rendering checks, see :ref:`fonts`. -``font-size:SIZE`` - Define font-size for rendering checks, see :ref:`fonts`. -``font-spacing:SPACING`` - Define letter spacing for rendering checks, see :ref:`fonts`. -``icu-flags:FLAGS`` - Define flags for customizing the behavior of the :ref:`check-icu-message-format` quality check. -``icu-tag-prefix:PREFIX`` - Set a required prefix for XML tags for the :ref:`check-icu-message-format` quality check. -``placeholders:NAME:NAME2:...`` - Placeholder strings expected in translation, see :ref:`check-placeholders`. -``replacements:FROM:TO:FROM2:TO2...`` - Replacements to perform when checking resulting text parameters (for - example in :ref:`check-max-size` or :ref:`check-max-length`). The typical - use case for this is to expand placeables to ensure that the text fits even - with long values, for example: ``replacements:%s:"John Doe"``. -``variants:SOURCE`` - Mark this string as a variant of string with matching source. See :ref:`variants`. -``regex:REGEX`` - Regular expression to match translation, see :ref:`check-regex`. -``discard:NAME`` - Discards flag defined on a higher level. -``forbidden`` - Indicates forbidden translation in a glossary, see :ref:`glossary-forbidden`. -``strict-same`` - Make the :ref:`check-same` avoid using the built-in words exceptions. -``strict-format`` - Make format checks enforce using format even for plural forms with a single value, see :ref:`check-formats`. -``check-glossary`` - Enable the :ref:`check-check-glossary` quality check. -``angularjs-format`` - Enable the :ref:`check-angularjs-format` quality check. -``c-format`` - Enable the :ref:`check-c-format` quality check. -``c-sharp-format`` - Enable the :ref:`check-c-sharp-format` quality check. -``es-format`` - Enable the :ref:`check-es-format` quality check. -``i18next-interpolation`` - Enable the :ref:`check-i18next-interpolation` quality check. -``icu-message-format`` - Enable the :ref:`check-icu-message-format` quality check. -``java-printf-format`` - Enable the :ref:`check-java-printf-format` quality check. -``java-format`` - Enable the :ref:`check-java-format` quality check. -``javascript-format`` - Enable the :ref:`check-javascript-format` quality check. -``lua-format`` - Enable the :ref:`check-lua-format` quality check. -``object-pascal-format`` - Enable the :ref:`check-object-pascal-format` quality check. -``percent-placeholders`` - Enable the :ref:`check-percent-placeholders` quality check. -``perl-brace-format`` - Enable the :ref:`check-perl-brace-format` quality check. -``perl-format`` - Enable the :ref:`check-perl-format` quality check. -``php-format`` - Enable the :ref:`check-php-format` quality check. -``python-brace-format`` - Enable the :ref:`check-python-brace-format` quality check. -``python-format`` - Enable the :ref:`check-python-format` quality check. -``qt-format`` - Enable the :ref:`check-qt-format` quality check. -``qt-plural-format`` - Enable the :ref:`check-qt-plural-format` quality check. -``ruby-format`` - Enable the :ref:`check-ruby-format` quality check. -``scheme-format`` - Enable the :ref:`check-scheme-format` quality check. -``vue-format`` - Enable the :ref:`check-vue-format` quality check. -``md-text`` - Treat text as a Markdown document, and provide Markdown syntax highlighting on the translation text area. - Enables :ref:`check-md-link`, :ref:`check-md-reflink`, and :ref:`check-md-syntax` quality checks. -``case-insensitive`` - Adjust checks behavior to be case-insensitive. Currently affects only :ref:`check-placeholders` quality check. -``safe-html`` - Enable the :ref:`check-safe-html` quality check. -``url`` - The string should consist of only a URL. - Enable the :ref:`check-url` quality check. -``ignore-all-checks`` - Ignore all quality checks. -``fluent-source-inner-html`` - Enable the :ref:`check-fluent-source-inner-html` quality check. -``fluent-source-syntax`` - Enable the :ref:`check-fluent-source-syntax` quality check. -``icu-message-format`` - Enable the :ref:`check-icu-message-format-syntax` quality check. -``ignore-bbcode`` - Skip the :ref:`check-bbcode` quality check. -``ignore-duplicate`` - Skip the :ref:`check-duplicate` quality check. -``ignore-check-glossary`` - Skip the :ref:`check-check-glossary` quality check. -``ignore-double-space`` - Skip the :ref:`check-double-space` quality check. -``ignore-fluent-parts`` - Skip the :ref:`check-fluent-parts` quality check. -``ignore-fluent-references`` - Skip the :ref:`check-fluent-references` quality check. -``ignore-fluent-target-inner-html`` - Skip the :ref:`check-fluent-target-inner-html` quality check. -``ignore-fluent-target-syntax`` - Skip the :ref:`check-fluent-target-syntax` quality check. -``ignore-angularjs-format`` - Skip the :ref:`check-angularjs-format` quality check. -``ignore-automattic-components-format`` - Skip the :ref:`check-automattic-components-format` quality check. -``ignore-c-format`` - Skip the :ref:`check-c-format` quality check. -``ignore-c-sharp-format`` - Skip the :ref:`check-c-sharp-format` quality check. -``ignore-es-format`` - Skip the :ref:`check-es-format` quality check. -``ignore-i18next-interpolation`` - Skip the :ref:`check-i18next-interpolation` quality check. -``ignore-icu-message-format`` - Skip the :ref:`check-icu-message-format` quality check. -``ignore-java-printf-format`` - Skip the :ref:`check-java-printf-format` quality check. -``ignore-java-format`` - Skip the :ref:`check-java-format` quality check. -``ignore-javascript-format`` - Skip the :ref:`check-javascript-format` quality check. -``ignore-lua-format`` - Skip the :ref:`check-lua-format` quality check. -``ignore-object-pascal-format`` - Skip the :ref:`check-object-pascal-format` quality check. -``ignore-percent-placeholders`` - Skip the :ref:`check-percent-placeholders` quality check. -``ignore-perl-brace-format`` - Skip the :ref:`check-perl-brace-format` quality check. -``ignore-perl-format`` - Skip the :ref:`check-perl-format` quality check. -``ignore-php-format`` - Skip the :ref:`check-php-format` quality check. -``ignore-python-brace-format`` - Skip the :ref:`check-python-brace-format` quality check. -``ignore-python-format`` - Skip the :ref:`check-python-format` quality check. -``ignore-qt-format`` - Skip the :ref:`check-qt-format` quality check. -``ignore-qt-plural-format`` - Skip the :ref:`check-qt-plural-format` quality check. -``ignore-ruby-format`` - Skip the :ref:`check-ruby-format` quality check. -``ignore-scheme-format`` - Skip the :ref:`check-scheme-format` quality check. -``ignore-vue-format`` - Skip the :ref:`check-vue-format` quality check. -``ignore-translated`` - Skip the :ref:`check-translated` quality check. -``ignore-inconsistent`` - Skip the :ref:`check-inconsistent` quality check. -``ignore-rst-references`` - Skip the :ref:`check-rst-references` quality check. -``ignore-kashida`` - Skip the :ref:`check-kashida` quality check. -``ignore-md-link`` - Skip the :ref:`check-md-link` quality check. -``ignore-md-reflink`` - Skip the :ref:`check-md-reflink` quality check. -``ignore-md-syntax`` - Skip the :ref:`check-md-syntax` quality check. -``ignore-max-length`` - Skip the :ref:`check-max-length` quality check. -``ignore-max-size`` - Skip the :ref:`check-max-size` quality check. -``ignore-escaped-newline`` - Skip the :ref:`check-escaped-newline` quality check. -``ignore-end-colon`` - Skip the :ref:`check-end-colon` quality check. -``ignore-end-ellipsis`` - Skip the :ref:`check-end-ellipsis` quality check. -``ignore-end-exclamation`` - Skip the :ref:`check-end-exclamation` quality check. -``ignore-end-stop`` - Skip the :ref:`check-end-stop` quality check. -``ignore-end-interrobang`` - Skip the :ref:`check-end-interrobang` quality check. -``ignore-end-question`` - Skip the :ref:`check-end-question` quality check. -``ignore-end-semicolon`` - Skip the :ref:`check-end-semicolon` quality check. -``ignore-newline-count`` - Skip the :ref:`check-newline-count` quality check. -``ignore-plurals`` - Skip the :ref:`check-plurals` quality check. -``ignore-kabyle-characters`` - Skip the :ref:`check-kabyle-characters` quality check. -``ignore-placeholders`` - Skip the :ref:`check-placeholders` quality check. -``ignore-prohibited-initial-character`` - Skip the :ref:`check-prohibited-initial-character` quality check. -``ignore-punctuation-spacing`` - Skip the :ref:`check-punctuation-spacing` quality check. -``ignore-regex`` - Skip the :ref:`check-regex` quality check. -``ignore-rst-syntax`` - Skip the :ref:`check-rst-syntax` quality check. -``ignore-reused`` - Skip the :ref:`check-reused` quality check. -``ignore-same-plurals`` - Skip the :ref:`check-same-plurals` quality check. -``ignore-begin-newline`` - Skip the :ref:`check-begin-newline` quality check. -``ignore-begin-space`` - Skip the :ref:`check-begin-space` quality check. -``ignore-end-newline`` - Skip the :ref:`check-end-newline` quality check. -``ignore-end-space`` - Skip the :ref:`check-end-space` quality check. -``ignore-same`` - Skip the :ref:`check-same` quality check. -``ignore-safe-html`` - Skip the :ref:`check-safe-html` quality check. -``ignore-url`` - Skip the :ref:`check-url` quality check. -``ignore-xml-tags`` - Skip the :ref:`check-xml-tags` quality check. -``ignore-xml-invalid`` - Skip the :ref:`check-xml-invalid` quality check. -``ignore-zero-width-space`` - Skip the :ref:`check-zero-width-space` quality check. -``ignore-ellipsis`` - Skip the :ref:`check-ellipsis` quality check. -``ignore-fluent-source-inner-html`` - Skip the :ref:`check-fluent-source-inner-html` quality check. -``ignore-fluent-source-syntax`` - Skip the :ref:`check-fluent-source-syntax` quality check. -``ignore-icu-message-format`` - Skip the :ref:`check-icu-message-format-syntax` quality check. -``ignore-long-untranslated`` - Skip the :ref:`check-long-untranslated` quality check. -``ignore-multiple-failures`` - Skip the :ref:`check-multiple-failures` quality check. -``ignore-unnamed-format`` - Skip the :ref:`check-unnamed-format` quality check. -``ignore-optional-plural`` - Skip the :ref:`check-optional-plural` quality check. +.. include:: /snippets/check-flags-autogenerated.rst .. note:: diff --git a/docs/admin/machine.rst b/docs/admin/machine.rst index 579423def322..e9962814ea6d 100644 --- a/docs/admin/machine.rst +++ b/docs/admin/machine.rst @@ -60,1023 +60,9 @@ This can be used to tweak the service to get the best results. Following choices Falls back to the automatic selection of the source language if the secondary language not configured. -.. _mt-alibaba: -Alibaba -------- +.. include:: /snippets/machines-autogenerated.rst -.. versionadded:: 5.3 - -:Service ID: ``alibaba`` -:Maximal score: 80 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | Access key ID | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``secret`` | Access key secret | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``region`` | Region ID | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -Alibaba Translate is a neural machine translation service for translating text -and it supports up to 214 language pairs. - -.. seealso:: - - `Alibaba Translate Documentation `_ - -.. _mt-apertium-apy: - -Apertium APy ------------- - -:Service ID: ``apertium-apy`` -:Maximal score: 88 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``url`` | API URL | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -A libre software machine translation platform providing translations to -a limited set of languages. - -The recommended way to use Apertium is to run your own Apertium-APy server. - -.. seealso:: - - * `Apertium website `_ - * `Apertium APy documentation `_ - - - -.. _mt-aws: - -Amazon Translate ----------------- - -:Service ID: ``aws`` -:Maximal score: 88 -:Advanced features: * :ref:`glossary-mt` -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | Access key ID | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``secret`` | API secret key | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``region`` | Region name | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -Amazon Translate is a neural machine translation service for translating text -to and from English across a breadth of supported languages. -The service requires the `TranslateFullAccess` Managed Policy. - -The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. - -.. seealso:: - - * `Amazon Translate Documentation `_ - * `AWS TranslateFullAccess Policy `_ - -.. _mt-anthropic: - -Anthropic ---------- - -.. versionadded:: 5.16 - -:Service ID: ``anthropic`` -:Maximal score: 90 -:Advanced features: * :ref:`glossary-mt` -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``base_url`` | Anthropic API URL | Base URL of the Anthropic API. Leave empty to use the default URL. | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``model`` | Anthropic model | Available choices: | - | | | | - | | | ``claude-sonnet-4-5`` -- Claude Sonnet 4.5 (Recommended) | - | | | | - | | | ``claude-haiku-4-5`` -- Claude Haiku 4.5 | - | | | | - | | | ``claude-opus-4-5`` -- Claude Opus 4.5 | - | | | | - | | | ``custom`` -- Custom model | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``custom_model`` | Custom model name | Only needed when model is set to 'Custom model' | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``max_tokens`` | Max tokens | Maximum number of tokens to generate in the response. | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``persona`` | Translator persona | Describe the persona of translator to improve the accuracy of the translation. For example: "You are a squirrel breeder." | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``style`` | Translator style | Describe the style of translation. For example: "Use informal language." | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - -Performs translation using `Anthropic's Claude`_ models. - -The Anthropic API provides access to the Claude family of models, which are -known for their strong reasoning and language capabilities. You need an API key -from Anthropic to use this service. - -Use persona and style fields to further fine-tune translations. These will be -used in a prompt for Claude and allow you to change the style of the -translations. - -The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. - -.. seealso:: - - * `Anthropic API documentation `_ - * `Anthropic Console `_ - -.. _Anthropic's Claude: https://www.anthropic.com/ - -.. _mt-azure-openai: - -Azure OpenAI ------------- - -.. versionadded:: 5.8 - -:Service ID: ``azure-openai`` -:Maximal score: 90 -:Advanced features: * :ref:`glossary-mt` -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``base_url`` | API URL | | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``model`` | LLM model | | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``persona`` | Translator persona | Describe the persona of translator to improve the accuracy of the translation. For example: “You are a squirrel breeder.” | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``style`` | Translator style | Describe the style of translation. For example: “Use informal language.” | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``azure_endpoint`` | Azure OpenAI endpoint URL | Endpoint URL of the instance, e.g: https://my-instance.openai.azure.com. | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``deployment`` | Azure OpenAI deployment | The model's unique deployment name. | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - -Performs translation using `OpenAI`_ hosted on Azure. - -.. seealso:: - - :ref:`mt-openai` - -.. _mt-baidu: - -Baidu ------ - -:Service ID: ``baidu`` -:Maximal score: 90 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | Client ID | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``secret`` | Client secret | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -Machine translation service provided by Baidu. - -This service uses an API and you need to obtain an ID and API key from Baidu to use it. - -.. seealso:: - - `Baidu Translate API `_ - -.. _mt-cyrtranslit: - -CyrTranslit ------------ - -.. versionadded:: 5.7 - -:Service ID: ``cyrtranslit`` -:Maximal score: 100 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -Machine translation service using the Cyrtranslit library. - -This service converts text between Cyrillic and Latin scripts for languages that have both scripts. - -.. seealso:: - - `Cyrtranslit repository `_ - -.. _mt-deepl: - -DeepL ------ - -:Service ID: ``deepl`` -:Maximal score: 91 -:Advanced features: * :ref:`placeables-mt` - * :ref:`glossary-mt` -:Configuration: +---------------------+---------------------------+-------------------------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+-------------------------------------------------------------------------------------+ - | ``url`` | API URL | | - +---------------------+---------------------------+-------------------------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+-------------------------------------------------------------------------------------+ - | ``formality`` | Formality | Uses the specified formality if language is not specified as (in)formal | - +---------------------+---------------------------+-------------------------------------------------------------------------------------+ - | ``context`` | Translation context | Describe the context of the translation to improve the accuracy of the translation. | - +---------------------+---------------------------+-------------------------------------------------------------------------------------+ - | ``next_gen`` | Use next-gen model | Prefer next-gen LLM over classic machine translation model. | - +---------------------+---------------------------+-------------------------------------------------------------------------------------+ - -DeepL is paid service providing good machine translation for a few languages. -You need to purchase :guilabel:`DeepL API` subscription or you can use legacy -:guilabel:`DeepL Pro (classic)` plan. - -API URL to use with the DeepL service. At the time of writing, there is the v1 API -as well as a free and a paid version of the v2 API. - -``https://api.deepl.com/v2/`` (default in Weblate) - Is meant for API usage on the paid plan, and the subscription is usage-based. -``https://api-free.deepl.com/v2/`` - Is meant for API usage on the free plan, and the subscription is usage-based. -``https://api.deepl.com/v1/`` - Is meant for CAT tools and is usable with a per-user subscription. - -.. note:: - - Previously Weblate was classified as a CAT tool by DeepL, so it was supposed - to use the v1 API, but now is supposed to use the v2 API. Therefore it - defaults to v2, and you can change it to v1 in case you have an existing CAT - subscription and want Weblate to use that. - -Weblate supports DeepL formality, it will choose matching one based on the -language (for example, there is ``de@formal`` and ``de@informal``). - -The translation context can optionally be specified to improve translations quality. Read more on that in -`DeepL translation context documentation `_. - -The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. - -.. seealso:: - - * `DeepL translator `_ - * `DeepL pricing `_ - * `DeepL API documentation `_ - -.. _mt-glosbe: - -Glosbe ------- - -:Service ID: ``glosbe`` -:Maximal score: 90 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -Free dictionary and translation memory for almost every living language. - -The API is gratis to use, but usage of the translations is subject to the -license of the used data source. There is a limit of calls that may be done -from one IP in a set period of time, to prevent abuse. - -.. seealso:: - - `Glosbe website `_ - -.. _mt-google-translate: - -Google Cloud Translation Basic ------------------------------- - -:Service ID: ``google-translate`` -:Maximal score: 90 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -Machine translation service provided by the Google Cloud services. - -This service uses the Google Translation API v2, and you need to obtain an API key and turn on -billing in the Google API console. - -.. seealso:: - - `Google translate documentation `_ - -.. _mt-google-translate-api-v3: - -Google Cloud Translation Advanced ---------------------------------- - -:Service ID: ``google-translate-api-v3`` -:Maximal score: 90 -:Advanced features: * :ref:`placeables-mt` - * :ref:`glossary-mt` -:Configuration: +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ - | ``credentials`` | Google Translate service account info | Enter a JSON key for the service account. | - +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ - | ``project`` | Google Translate project | Enter the numeric or alphanumeric ID of your Google Cloud project. | - +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ - | ``location`` | Google Translate location | Choose a Google Cloud Translation region that is used for the Google Cloud project or is closest to you. | - +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ - | ``bucket_name`` | Google Storage Bucket name | Enter the name of the Google Cloud Storage bucket that is used to store the Glossary files. | - +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ - -Machine translation service provided by the Google Cloud services. - -This service uses the Google Translation API v3 and you need credentials in JSON format to access it. - -In order to use this service, you first need to go through the following steps: - -1. `Select or create a Cloud Platform project.`_ -2. `Enable billing for your project.`_ -3. `Enable the Cloud Translation.`_ -4. `Setup Authentication.`_ - -.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project -.. _Enable billing for your project.: https://docs.cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project -.. _Enable the Cloud Translation.: https://docs.cloud.google.com/translate/docs -.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html - - -Optionally, you can configure the service to use :ref:`glossary` by setting up a Bucket: - -1. `Create a Google Cloud bucket.`_ -2. `Set bucket location to "us-central1".`_ -3. `Grant 'Storage Admin' permission to the Service Account.`_ - -.. _Create a Google Cloud bucket.: https://docs.cloud.google.com/storage/docs/creating-buckets -.. _Set bucket location to "us-central1".: https://docs.cloud.google.com/translate/docs/migrate-to-v3#resources_projects_and_locations -.. _Grant 'Storage Admin' permission to the Service Account.: https://docs.cloud.google.com/translate/docs/access-control - - -.. seealso:: - - * `Google translate documentation `_ - * `Authenticate to Cloud services using client libraries `_ - * `Creating Google Translate project `_ - * `Google Cloud App Engine locations `_ - -.. _mt-ibm: - -IBM Watson Language Translator ------------------------------- - -.. versionremoved:: 5.13.1 - - This service was withdrawn by vendor as of 10 December 2024. - -.. _mt-libretranslate: - -LibreTranslate --------------- - -.. versionadded:: 4.7.1 - -:Service ID: ``libretranslate`` -:Maximal score: 89 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``url`` | API URL | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -LibreTranslate is a free and open-source service for machine translations. The -public instance requires an API key, but LibreTranslate can be self-hosted -and there are several mirrors available to use the API for free. - -``https://libretranslate.com/`` (official public instance) - Requires an API key to use outside of the website. - -.. seealso:: - - * `LibreTranslate website `_ - * `LibreTranslate repository `_ - * :ref:`docker-libretranslate` - -.. _mt-microsoft-translator: - -Azure AI Translator -------------------- - - -.. - # spellchecker:off - -:Service ID: ``microsoft-translator`` -:Maximal score: 90 -:Advanced features: * :ref:`placeables-mt` - * :ref:`glossary-mt` -:Configuration: +---------------------+-------------------------------+---------------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+-------------------------------+---------------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+-------------------------------+---------------------------------------------------------------------------+ - | ``base_url`` | Application base URL | Available choices: | - | | | | - | | | ``api.cognitive.microsofttranslator.com`` -- Global (non-regional) | - | | | | - | | | ``api-apc.cognitive.microsofttranslator.com`` -- Asia Pacific | - | | | | - | | | ``api-eur.cognitive.microsofttranslator.com`` -- Europe | - | | | | - | | | ``api-nam.cognitive.microsofttranslator.com`` -- North America | - | | | | - | | | ``api.translator.azure.cn`` -- China | - | | | | - | | | ``api.cognitive.microsofttranslator.us`` -- Azure US Government cloud | - +---------------------+-------------------------------+---------------------------------------------------------------------------+ - | ``endpoint_url`` | Authentication service URL | Regional or multi-service can be specified using region field below. | - | | | | - | | | Available choices: | - | | | | - | | | ``api.cognitive.microsoft.com`` -- Global | - | | | | - | | | ``api.cognitive.azure.cn`` -- China | - | | | | - | | | ``api.cognitive.microsoft.us`` -- Azure US Government cloud | - +---------------------+-------------------------------+---------------------------------------------------------------------------+ - | ``region`` | Authentication service region | | - +---------------------+-------------------------------+---------------------------------------------------------------------------+ - | ``category`` | Category | Specify a customized system category ID to use it instead of general one. | - +---------------------+-------------------------------+---------------------------------------------------------------------------+ - -.. - # spellchecker:on - -Machine translation service provided by Microsoft in Azure portal as a one of -Cognitive Services. - -Weblate implements Translator API V3. - -The service automatically uses :ref:`glossary` via `dynamic dictionary `_, see :ref:`glossary-mt`. - -Translator Text API V2 -`````````````````````` -The key you use with Translator API V2 can be used with API 3. - -Translator Text API V3 -`````````````````````` -You need to register at Azure portal and use the key you obtain there. -With new Azure keys, you also need to set ``region`` to locale of your service. - -You can also specify a custom category to use `custom translator `_. - -.. hint:: - - For Azure China, please use your endpoint from the Azure Portal. - -.. seealso:: - - * `Cognitive Services - Text Translation API `_ - * `Microsoft Azure Portal `_ - * `Base URLs `_ - * `"Authenticating with a Multi-service resource" `_ - * `"Authenticating with an access token" section `_ - - -.. _mt-modernmt: - -ModernMT --------- - -.. versionadded:: 4.2 - -:Service ID: ``modernmt`` -:Maximal score: 90 -:Advanced features: * :ref:`glossary-mt` -:Configuration: +---------------------+---------------------------+-----------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+-----------------------------------------------------------------------+ - | ``url`` | API URL | | - +---------------------+---------------------------+-----------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+-----------------------------------------------------------------------+ - | ``context_vector`` | Context vector | Comma-separated list of memory IDs:weight. e.g: 1234:0.123,4567:0.456 | - +---------------------+---------------------------+-----------------------------------------------------------------------+ - -The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. - -.. seealso:: - - `ModernMT API `_ - -.. _mt-mymemory: - -MyMemory --------- - -:Service ID: ``mymemory`` -:Maximal score: 100 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``email`` | Contact e-mail | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``username`` | Username | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - - -Huge translation memory with machine translation. - -Free, anonymous usage is currently limited to 100 requests/day, or to 1000 -requests/day when you provide a contact e-mail address in ``email``. -You can also ask them for more. - - -.. seealso:: - - `MyMemory website `_ - -.. _mt-netease-sight: - -Netease Sight -------------- - -:Service ID: ``netease-sight`` -:Maximal score: 90 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | Client ID | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``secret`` | Client secret | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -Machine translation service provided by NetEase. - -This service uses an API, and you need to obtain key and secret from NetEase. - -.. seealso:: - - `NetEase Sight Translation Platform `_ - -.. _mt-ollama: - -Ollama ------- - -.. versionadded:: 5.15 - -:Service ID: ``ollama`` -:Maximal score: 90 -:Advanced features: * :ref:`glossary-mt` -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``base_url`` | API URL | Base URL of the Ollama API, localhost and port 11434 by default. | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``model`` | Ollama model | Name of the model described in Ollama catalogue. | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``persona`` | Translator persona | Describe the persona of translator to improve the accuracy of the translation. For example: “You are a squirrel breeder.” | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``style`` | Translator style | Describe the style of translation. For example: “Use informal language.” | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - -Performs translation using `Ollama`_ models. - -The Ollama API allows for the use of open source models for translations -either locally installed or remotely accessed via the `Ollama`_ service. -Note that before configuring your models, you should have `Ollama installed`_ -and downloaded the models you wish to use. - -Use persona and style fields to further fine-tune translations. These will be -used in a prompt for Ollama and allow you to change the style of the -translations. - -The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. - -.. seealso:: - - * `Ollama models `_ - -.. _Ollama: https://ollama.com/ -.. _Ollama installed: https://ollama.com/download - -.. _mt-openai: - -OpenAI ------- - -.. versionadded:: 5.3 - -:Service ID: ``openai`` -:Maximal score: 90 -:Advanced features: * :ref:`glossary-mt` -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``persona`` | Translator persona | Describe the persona of translator to improve the accuracy of the translation. For example: “You are a squirrel breeder.” | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``style`` | Translator style | Describe the style of translation. For example: “Use informal language.” | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``base_url`` | OpenAI API base URL | Base URL of the OpenAI API, if it differs from the OpenAI default URL | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``model`` | OpenAI model | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``gpt-5-nano`` -- GPT-5-nano | - | | | | - | | | ``gpt-5-mini`` -- GPT-5-mini | - | | | | - | | | ``gpt-5`` -- GPT-5 | - | | | | - | | | ``gpt-4.1-nano`` -- GPT-4.1-nano | - | | | | - | | | ``gpt-4.1-mini`` -- GPT-4.1-mini | - | | | | - | | | ``gpt-4.1`` -- GPT-4.1 | - | | | | - | | | ``gpt-4o-mini`` -- GPT-4o mini | - | | | | - | | | ``gpt-4o`` -- GPT-4o | - | | | | - | | | ``o3-mini`` -- o3-mini | - | | | | - | | | ``o3`` -- o3 | - | | | | - | | | ``o1-mini`` -- o1-mini | - | | | | - | | | ``o1`` -- o1 | - | | | | - | | | ``o1-pro`` -- o1-pro | - | | | | - | | | ``custom`` -- Custom model | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - | ``custom_model`` | Custom model name | Only needed when model is set to 'Custom model' | - +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ - -Performs translation using `OpenAI`_. - -The OpenAI API is powered by a diverse set of models with different -capabilities and price points. Automatic selection chooses the best model -available, but you might want to choose a specific model that matches your needs. - -Use persona and style fields to further fine-tune translations. These will be -used in a prompt for OpenAI and allow you to change the style of the -translations. - -The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. - -.. versionchanged:: 5.7 - - Support for custom model and base URL was added. - -.. seealso:: - - * `OpenAI models `_ - * `OpenAI API keys `_ - -.. _OpenAI: https://openai.com/ - -.. _mt-sap-translation-hub: - -SAP Translation Hub -------------------- - -:Service ID: ``sap-translation-hub`` -:Maximal score: 100 -:Configuration: +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``url`` | API URL | | - +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``username`` | SAP username | | - +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``password`` | SAP password | | - +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``enable_mt`` | Enable machine translation | | - +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ - | ``domain`` | Translation domain | The ID of a translation domain, for example, BC. If you do not specify a domain, the method searches for translations in all available domains. | - +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ - -Machine translation service provided by SAP. - -You need to have a SAP account (and the SAP Translation Hub enabled in the SAP Cloud -Platform) to use this service. - -You can also configure whether to also use machine translation services, in -addition to the term database. - -.. note:: - - To access the Sandbox API, you need to set ``url`` - and ``key``. - - To access the productive API, you need to set ``url``, ``username`` and ``password``. - -.. seealso:: - - * `What is SAP Translation Hub `_ - * `SAP Translation Hub API `_ - -.. _mt-systran: - -Systran -------- - -:Service ID: ``systran`` -:Maximal score: 90 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - - -Machine translation service provided by Systran. - -This service uses an API, and you need to obtain API key at . - -.. _mt-tmserver: - -tmserver --------- - -:Service ID: ``tmserver`` -:Maximal score: 100 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``url`` | API URL | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -You can run your own translation memory server by using a tmserver protocol. - -* The original :program:`tmserver` was bundled with the translate-toolkit. -* amaGama server is an enhanced version of tmserver. - -.. note:: - - There currently does not seem to be a maintained server for this. - -.. _mt-weblate: - -Weblate -------- - -:Service ID: ``weblate`` -:Maximal score: 100 -:Configuration: `This service has no configuration.` - - -Weblate machine translation service can provide translations based -on the exact matches of a string in the currently existing strings -in a :guilabel:`Translated`, :guilabel:`Approved`, -or :guilabel:`Read-only` :ref:`states ` inside Weblate. - -.. _mt-weblate-translation-memory: - -Weblate Translation Memory --------------------------- - -:Service ID: ``weblate-translation-memory`` -:Maximal score: 100 -:Configuration: `This service has no configuration.` - -Use :ref:`translation-memory` as a machine translation service. -Any string that has been translated before (or uploaded to the -translation memory) can be translated in this way. -This suggestion source works with fuzzy matching. - -.. note:: - - Recreating :ref:`translation-memory` reduces capabilities of this TM source. - -.. _mt-yandex: - -Yandex ------- - -:Service ID: ``yandex`` -:Maximal score: 90 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -Machine translation service provided by Yandex. - -This service uses a Translation API, and you need to obtain an API key from Yandex. - -.. seealso:: - - * `Yandex Translate API `_ - * `Powered by Yandex.Translate `_ - -.. _mt-yandex-v2: - -Yandex v2 ---------- - -.. versionadded:: 5.1 - -:Service ID: ``yandex-v2`` -:Maximal score: 90 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | API key | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -Machine translation service provided by Yandex. - -This service uses a Translation API, and you need to obtain an API key from Yandex Cloud. - -.. seealso:: - - * `Yandex Translate API v2 `_ - * `Powered by Yandex.Cloud `_ - -.. _mt-youdao-zhiyun: - -Youdao Zhiyun -------------- - -:Service ID: ``youdao-zhiyun`` -:Maximal score: 90 -:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``source_language`` | Source language selection | Available choices: | - | | | | - | | | ``auto`` -- Automatic selection | - | | | | - | | | ``source`` -- Component source language | - | | | | - | | | ``secondary`` -- Secondary language defined in project or component | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``key`` | Client ID | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - | ``secret`` | Client secret | | - +---------------------+---------------------------+---------------------------------------------------------------------+ - -Machine translation service provided by Youdao. - -This service uses an API, and you need to obtain an ID and an API key from Youdao. - -.. seealso:: - - `Youdao Zhiyun Natural Language Translation Service `_ .. _custom-machinery: diff --git a/docs/formats/laravel.rst b/docs/formats/laravel.rst index c3e0f6ce5a9b..1d5923544abf 100644 --- a/docs/formats/laravel.rst +++ b/docs/formats/laravel.rst @@ -1,3 +1,4 @@ +.. _laravel: .. _laravel-php: Laravel PHP strings diff --git a/docs/snippets/addons-autogenerated.rst b/docs/snippets/addons-autogenerated.rst new file mode 100644 index 000000000000..0c41302a69c7 --- /dev/null +++ b/docs/snippets/addons-autogenerated.rst @@ -0,0 +1,1852 @@ + +.. AUTOGENERATED START: events +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +Events that trigger add-ons ++++++++++++++++++++++++++++ +.. _addon-event-add-on-installation: + +Add-on installation +------------------- + +Triggered when add-on is being installed. + +.. _addon-event-component-update: + +Component update +---------------- + +Triggered whenever a change happens in a component such as: + +* Strings are changed in the repository. +* A string is added. +* A new translation is added. + +.. _addon-event-daily: + +Daily +----- + +Triggered daily, but add-ons usually split the daily load between components depending on :setting:`BACKGROUND_TASKS`. + +.. _addon-event-event-change: + +Event change +------------ + +Triggered after a Change event is created. + +.. _addon-event-repository-post-add: + +Repository post-add +------------------- + +Triggered just after the new translation is added and committed. + +.. _addon-event-repository-post-commit: + +Repository post-commit +---------------------- + +Triggered just after the changes are committed. + +.. _addon-event-repository-post-push: + +Repository post-push +-------------------- + +Triggered just after the repository is pushed upstream. + +.. _addon-event-repository-post-update: + +Repository post-update +---------------------- + +Triggered whenever new changes are pulled from the upstream repository. + +.. _addon-event-repository-pre-commit: + +Repository pre-commit +--------------------- + +Triggered just before the changes are committed. + +.. _addon-event-repository-pre-push: + +Repository pre-push +------------------- + +Triggered just before the repository is pushed upstream. + +.. _addon-event-repository-pre-update: + +Repository pre-update +--------------------- + +Triggered just before the repository update is attempted. + +.. _addon-event-unit-post-save: + +Unit post-save +-------------- + +Triggered just after the string is saved. + +.. _addon-event-unit-post-sync: + +Unit post-sync +-------------- + +Triggered after the string is synchronized with the VCS. + +.. _addon-event-unit-pre-create: + +Unit pre-create +--------------- + +Triggered just after the newly created string is saved. + + +.. AUTOGENERATED END: events + +.. AUTOGENERATED START: addons-header +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +Built-in add-ons +++++++++++++++++ + +.. AUTOGENERATED END: addons-header + +.. AUTOGENERATED START: weblate.autotranslate.autotranslate +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.autotranslate.autotranslate: + +Automatic translation +--------------------- + +:Add-on ID: ``weblate.autotranslate.autotranslate`` +:Configuration: +-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ + | ``mode`` | Automatic translation mode | .. list-table:: Available choices: | + | | | :width: 100% | + | | | | + | | | * - ``suggest`` | + | | | - Add as suggestion | + | | | * - ``translate`` | + | | | - Add as translation | + | | | * - ``fuzzy`` | + | | | - Add as "Needing edit" | + +-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ + | ``q`` | Query | Please note that translating all strings will discard all existing translations. | + +-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ + | ``auto_source`` | Source of automated translations | .. list-table:: Available choices: | + | | | :width: 100% | + | | | | + | | | * - ``others`` | + | | | - Other translation components | + | | | * - ``mt`` | + | | | - Machine translation | + +-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ + | ``component`` | Component | Turn on contribution to shared translation memory for the project to get access to additional components. | + +-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ + | ``engines`` | Machine translation engines | :ref:`addon-choice-engines` | + +-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ + | ``threshold`` | Score threshold | | + +-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+ + +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update`, :ref:`addon-event-daily`, :ref:`addon-event-event-change` + +Automatically translates strings using machine translation or other components. + +.. AUTOGENERATED END: weblate.autotranslate.autotranslate + +.. seealso:: + + * :ref:`auto-translation` + * :ref:`translation-consistency` + * :ref:`mt-translation-services-priority` + * :ref:`search-strings` + + +.. AUTOGENERATED START: weblate.cdn.cdnjs +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.cdn.cdnjs: + +JavaScript localization CDN +--------------------------- + +.. versionadded:: 4.2 + +:Add-on ID: ``weblate.cdn.cdnjs`` +:Configuration: +------------------+---------------------------------+-------------------------------------------------------------------------------------------+ + | ``threshold`` | Translation threshold | The percentage of translated strings that must be present for translation to be included. | + +------------------+---------------------------------+-------------------------------------------------------------------------------------------+ + | ``css_selector`` | CSS selector | CSS selector to detect localizable elements. | + +------------------+---------------------------------+-------------------------------------------------------------------------------------------+ + | ``cookie_name`` | Language cookie name | Name of cookie which stores language preference. | + +------------------+---------------------------------+-------------------------------------------------------------------------------------------+ + | ``files`` | Extract strings from HTML files | List of filenames in current repository or remote URLs to parse for translatable strings. | + +------------------+---------------------------------+-------------------------------------------------------------------------------------------+ + +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily`, :ref:`addon-event-repository-post-commit`, :ref:`addon-event-repository-post-update` + +Publishes translations into content delivery network for use in JavaScript or +HTML localization. + +.. AUTOGENERATED END: weblate.cdn.cdnjs + +Can be used to localize static HTML pages, or +to load localization in the JavaScript code. + +Generates a unique URL for your component you can include in +HTML pages to localize them. See :ref:`weblate-cdn` for more details. + +.. note:: + + This add-on requires additional configuration on the Weblate server. + :setting:`LOCALIZE_CDN_PATH` configures where generated files will be + written (on a filesystem), and :setting:`LOCALIZE_CDN_URL` defines where + they will be served (URL). Serving of the files is not done by Weblate and + has to be set up externally (typically using a CDN service). + + This add-on is configured on :guilabel:`Hosted Weblate` and serves the files + via ``https://weblate-cdn.com/``. + +.. seealso:: + + * :ref:`cdn-addon-config` + * :ref:`weblate-cdn` + * :ref:`cdn-addon-extract` + * :ref:`cdn-addon-html` + +.. AUTOGENERATED START: weblate.cleanup.blank +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.cleanup.blank: + +Remove blank strings +-------------------- + +.. versionadded:: 4.4 + +:Add-on ID: ``weblate.cleanup.blank`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-commit`, :ref:`addon-event-repository-post-update` + +Removes strings without a translation from translation files. + +.. AUTOGENERATED END: weblate.cleanup.blank + +Use this to not have any empty strings in translation files (for +example if your localization library displays them as missing instead +of falling back to the source string). + +.. seealso:: + + :ref:`faq-cleanup` + +.. AUTOGENERATED START: weblate.cleanup.generic +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.cleanup.generic: + +Cleanup translation files +------------------------- + +:Add-on ID: ``weblate.cleanup.generic`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-update`, :ref:`addon-event-repository-pre-commit` + +Update all translation files to match the monolingual base file. For most file +formats, this means removing stale translation keys no longer present in the +base file. + +.. AUTOGENERATED END: weblate.cleanup.generic + +For formats containing additional content besides translation strings (such as +:ref:`html`, :ref:`winrc`, or :ref:`odf`) this also brings the translation file +in sync with the base file. + +.. seealso:: + + :ref:`faq-cleanup` + +.. AUTOGENERATED START: weblate.consistency.languages +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.consistency.languages: + +Add missing languages +--------------------- + +:Add-on ID: ``weblate.consistency.languages`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily`, :ref:`addon-event-repository-post-add` + +Ensures a consistent set of languages is used for all components within a +project. + +.. AUTOGENERATED END: weblate.consistency.languages + +.. note:: + + The components shared from other projects are not considered in this. + +Missing languages are checked once every 24 hours, and when new languages +are added in Weblate. + +Unlike most others, this add-on affects the whole project. + +.. hint:: + + Auto-translate the newly added strings with + :ref:`addon-weblate.autotranslate.autotranslate`. + +.. AUTOGENERATED START: weblate.discovery.discovery +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.discovery.discovery: + +Component discovery +------------------- + +:Add-on ID: ``weblate.discovery.discovery`` +:Configuration: +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``match`` | Regular expression to match translation files against | | + +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``file_format`` | File format | :ref:`addon-choice-file_format` | + +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``name_template`` | Customize the component name | | + +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``base_file_template`` | Define the monolingual base filename | Leave empty for bilingual translation files. | + +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``new_base_template`` | Define the base file for new translations | Filename of file used for creating new translations. For gettext choose .pot file. | + +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``intermediate_template`` | Intermediate language file | Filename of intermediate translation file. In most cases this is a translation file provided by developers and is used when creating actual source strings. | + +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``language_regex`` | Language filter | Regular expression to filter translation files against when scanning for file mask. | + +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``copy_addons`` | Clone add-ons from the main component to the newly created ones | | + +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``remove`` | Remove components for inexistent files | | + +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``confirm`` | I confirm the above matches look correct | | + +---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-update` + +Automatically adds or removes project components based on file changes in the +version control system. + +.. AUTOGENERATED END: weblate.discovery.discovery + +The matching is done using regular expressions +enabling complex configuration, but some knowledge is required to do so. +Some examples for common use cases can be found in +the add-on help section. + +The regular expression to match translation files has to contain two named +groups to match component and language. All named groups in the regular +expression can be used as variables in the template fields. + +You can use Django template markup in all filename fields, for example: + +``{{ component }}`` + Component filename match +``{{ component|title }}`` + Component filename with upper case first letter +``{{ path }}: {{ component }}`` + Custom match group from the regular expression + +Once you hit :guilabel:`Save`, a preview of matching components will be presented, +from where you can check whether the configuration actually matches your needs: + +.. image:: /screenshots/addon-discovery.webp + +Component discovery examples +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +One folder per language +####################### + +One folder per language containing translation files for components. + +Regular expression: + ``(?P[^/.]*)/(?P[^/]*)\.po`` +Matching files: + - :file:`cs/application.po` + - :file:`cs/website.po` + - :file:`de/application.po` + - :file:`de/website.po` + +Gettext locales layout +###################### + +Usual structure for storing gettext PO files. + +Regular expression: + ``locale/(?P[^/.]*)/LC_MESSAGES/(?P[^/]*)\.po`` +Matching files: + - :file:`locale/cs/LC_MESSAGES/application.po` + - :file:`locale/cs/LC_MESSAGES/website.po` + - :file:`locale/de/LC_MESSAGES/application.po` + - :file:`locale/de/LC_MESSAGES/website.po` + +Complex filenames +################# + +Using both component and language name within filename. + +Regular expression: + ``src/locale/(?P[^/]*)\.(?P[^/.]*)\.po`` +Matching files: + - :file:`src/locale/application.cs.po` + - :file:`src/locale/website.cs.po` + - :file:`src/locale/application.de.po` + - :file:`src/locale/website.de.po` + +Repeated language code +###################### + +Using language in both path and filename. + +Regular expression: + ``locale/(?P[^/.]*)/(?P[^/]*)/(?P=language)\.po`` +Matching files: + - :file:`locale/cs/application/cs.po` + - :file:`locale/cs/website/cs.po` + - :file:`locale/de/application/de.po` + - :file:`locale/de/website/de.po` + + +Split Android strings +##################### + +Android resource strings, split into several files. + +Regular expression: + ``res/values-(?P[^/.]*)/strings-(?P[^/]*)\.xml`` +Matching files: + - :file:`res/values-cs/strings-about.xml` + - :file:`res/values-cs/strings-help.xml` + - :file:`res/values-de/strings-about.xml` + - :file:`res/values-de/strings-help.xml` + +Matching multiple paths +####################### + +Multi-module Maven project with Java properties translations. + +Regular expression: + ``(?P.+/)(?P[^/]*)/src/main/resources/ApplicationResources_(?P[^/.]*)\.properties`` +Component name: + ``{{ originalHierarchy }}: {{ component }}`` +Matching files: + - :file:`parent/module1/submodule/src/main/resources/ApplicationResources_fr.properties` + - :file:`parent/module1/submodule/src/main/resources/ApplicationResource_es.properties` + - :file:`parent/module2/src/main/resources/ApplicationResource_de.properties` + - :file:`parent/module2/src/main/resources/ApplicationResource_ro.properties` + + +.. hint:: + + Component discovery add-on uses :ref:`internal-urls`. It’s a convenient way to share + VCS setup between multiple components. Linked components use the local repository of + the main component set up by filling ``weblate://project/main-component`` + into the :ref:`component-repo` field (in :guilabel:`Operations` ↓ :guilabel:`Settings` ↓ + :guilabel:`Version control system`) of each respective component. + This saves time with configuration and system resources too. + +.. hint:: + + Ensure the new component contains the full set of translatable languages with + :ref:`addon-weblate.consistency.languages`. + +.. warning:: + + To be discovered, a new component must contain a file that matches ``base_file_template`` + **and** at least one file with a name that matches ``match`` -- i.e., the component must + contain a base language file and at least one existing translation. Otherwise, it will be + ignored. + +.. seealso:: + + * :ref:`markup` + * :wladmin:`import_project` + + +.. AUTOGENERATED START: weblate.fedora_messaging.publish +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _fedora-messaging: +.. _addon-weblate.fedora_messaging.publish: + +Fedora Messaging +---------------- + +.. versionadded:: 5.15 + +:Add-on ID: ``weblate.fedora_messaging.publish`` +:Configuration: +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ + | ``events`` | Change events | :ref:`addon-choice-events` | + +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ + | ``amqp_host`` | AMQP broker host | The AMQP broker to connect to. | + +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ + | ``amqp_ssl`` | Use SSL for AMQP connection | | + +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ + | ``ca_cert`` | CA certificates | Bundle of PEM encoded CA certificates used to validate the certificate presented by the server. | + +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ + | ``client_key`` | Client SSL key | PEM encoded client private SSL key. | + +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ + | ``client_cert`` | Client SSL certificates | PEM encoded client SSL certificate. | + +-----------------+-----------------------------+-------------------------------------------------------------------------------------------------+ + +:Triggers: :ref:`addon-event-event-change` + +Sends notifications to a Fedora Messaging compatible AMQP exchange. + +.. AUTOGENERATED END: weblate.fedora_messaging.publish + +Fedora Messaging is AMQP-based publisher for all changes happening in Weblate. +You can hook additional services on changes happening in Weblate using this. + +Message topic +~~~~~~~~~~~~~ + +All messages have topic +``weblate....``. The action is +lowercase textual representation of action with underscores instead of space, +for example ``resource_update``, all other parts are optional and represent +slug of the object or a language code. + +Message body +~~~~~~~~~~~~ + +The body consists of following fields (given that they are available for the event): + +``change_id`` + Numerical ID of change +``action`` + Verbose name of the change. +``timestamp`` + ISO formatted timestamp +``target`` + New value of the change (eg. new translation of the string) +``old`` + Old value of the change (eg. previous translation of the string) +``source`` + Source string. +``url`` + Absolute URL to view the related object. +``author`` + Author username (this can be different from user for example when accepting suggestions) +``user`` + Acting username +``project`` + Project slug +``component`` + Component slug +``translation`` + Translation language code + +Message headers +~~~~~~~~~~~~~~~ + +There are additional headers which you might utilize for routing as well: + +``action`` + Verbose name of the change. +``project`` + Project slug +``component`` + Component slug + +Example messages +~~~~~~~~~~~~~~~~ + +Repository merge event: + +.. code-block:: json + + { + "id": 1, + "action": "Merged repository", + "timestamp": "2017-06-15T11:30:47.325000+00:00", + "url": "http://example.com/projects/test/test/", + "component": "test" + } + +New source string event: + +.. code-block:: json + + { + "id": 2, + "action": "New source string", + "timestamp": "2017-06-15T11:30:47.372000+00:00", + "url": "http://example.com/translate/test/test/cs/?checksum=6412684aaf018e8e", + "component": "test", + "translation": "cs", + "source": ["Hello, world!\n"] + } + +Resource update event: + +.. code-block:: json + + { + "id": 6, + "action": "Resource update", + "timestamp": "2017-06-15T11:30:47.410000+00:00", + "url": "http://example.com/projects/test/test/cs/", + "project": "test", + "component": "test", + "translation": "cs" + } + { + "id": 7, + "action": "Resource update", + "timestamp": "2017-06-15T11:30:47.510000+00:00", + "url": "http://example.com/projects/test/test/de/", + "project": "test", + "component": "test", + "translation": "de" + } + { + "id": 8, + "action": "Resource update", + "timestamp": "2017-06-15T11:30:47.595000+00:00", + "url": "http://example.com/projects/test/test/it/", + "project": "test", + "component": "test", + "translation": "it" + } + +Project removal event: + +.. code-block:: json + + { + "id": 9, + "action": "Removed project", + "timestamp": "2019-10-17T15:57:08.559420+00:00", + "target": "test", + "user": "testuser" + } + +New contributor event: + +.. code-block:: json + + { + "id": 11, + "action": "New contributor", + "timestamp": "2019-10-17T15:57:08.759960+00:00", + "url": "http://example.com/translate/test/test/cs/?checksum=6412684aaf018e8e", + "author": "testuser", + "user": "testuser", + "project": "test", + "component": "test", + "translation": "cs", + "source": ["Hello, world!\n"] + } + +New translation event: + +.. code-block:: json + + { + "id": 12, + "action": "New translation", + "timestamp": "2019-10-17T15:57:08.772591+00:00", + "url": "http://example.com/translate/test/test/cs/?checksum=6412684aaf018e8e", + "target": ["Ahoj svete!\n"], + "author": "testuser", + "user": "testuser", + "project": "test", + "component": "test", + "translation": "cs", + "source": ["Hello, world!\n"] + } + +.. seealso:: + + * `Configuring Fedora Messaging`_ + * :ref:`schema-messaging` + +.. _Configuring Fedora Messaging: https://fedora-messaging.readthedocs.io/en/stable/user-guide/configuration.html + +.. AUTOGENERATED START: weblate.flags.bulk +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.flags.bulk: + +Bulk edit +--------- + +:Add-on ID: ``weblate.flags.bulk`` +:Configuration: +-------------------+-----------------------------+----------------------------------------+ + | ``q`` | Query | | + +-------------------+-----------------------------+----------------------------------------+ + | ``state`` | State to set | .. list-table:: Available choices: | + | | | :width: 100% | + | | | | + | | | * - ``-1`` | + | | | - Do not change | + | | | * - ``10`` | + | | | - Needs editing | + | | | * - ``11`` | + | | | - Needs editing (Needs rewriting) | + | | | * - ``12`` | + | | | - Needs editing (Needs checking) | + | | | * - ``20`` | + | | | - Translated | + | | | * - ``30`` | + | | | - Approved | + +-------------------+-----------------------------+----------------------------------------+ + | ``add_flags`` | Translation flags to add | | + +-------------------+-----------------------------+----------------------------------------+ + | ``remove_flags`` | Translation flags to remove | | + +-------------------+-----------------------------+----------------------------------------+ + | ``add_labels`` | Labels to add | | + +-------------------+-----------------------------+----------------------------------------+ + | ``remove_labels`` | Labels to remove | | + +-------------------+-----------------------------+----------------------------------------+ + +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update` + +Bulk edit flags, labels, or states of strings. + +.. AUTOGENERATED END: weblate.flags.bulk + +**Examples:** + +.. list-table:: Label new strings automatically + :stub-columns: 1 + + * - Search query + - ``NOT has:label`` + * - Labels to add + - *recent* + +.. list-table:: Marking all :ref:`appstore` changelog strings read-only + :stub-columns: 1 + + * - Search query + - ``language:en AND key:changelogs/`` + * - Translation flags to add + - ``read-only`` + + +.. list-table:: Marking certain strings read-only + :stub-columns: 1 + + * - Search query + - ``source:r"^\`\`[.a-zA-Z0-9_-]*\`\`$" AND language:en`` + * - Translation flags to add + - ``read-only`` + +.. seealso:: + + * :ref:`bulk-edit` + * :ref:`custom-checks` + * :ref:`labels` + +.. AUTOGENERATED START: weblate.flags.same_edit +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.flags.same_edit: + +Flag unchanged translations as "Needs rewriting" +------------------------------------------------ + +:Add-on ID: ``weblate.flags.same_edit`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-unit-pre-create` + +Whenever a new translatable string is imported from the VCS and it matches a +source string, it is flagged as needing rewriting in Weblate. Especially useful +for file formats that include source strings for untranslated strings. + +.. AUTOGENERATED END: weblate.flags.same_edit + +.. hint:: + + You might also want to tighthen the :ref:`check-same` check by adding + ``strict-same`` flag to :ref:`component-check_flags`. + +.. seealso:: + + :ref:`states` + +.. AUTOGENERATED START: weblate.flags.source_edit +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.flags.source_edit: + +Flag new source strings as "Needs checking" +------------------------------------------- + +:Add-on ID: ``weblate.flags.source_edit`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-unit-pre-create` + +Whenever a new source string is imported from the VCS, it is flagged as needing +checking in Weblate. This way you can easily filter and edit source strings +written by the developers. + +.. AUTOGENERATED END: weblate.flags.source_edit + +.. seealso:: + + :ref:`states` + +.. AUTOGENERATED START: weblate.flags.target_edit +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.flags.target_edit: + +Flag new translations as "Needs rewriting" +------------------------------------------ + +:Add-on ID: ``weblate.flags.target_edit`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-unit-pre-create` + +Whenever a new translatable string is imported from the VCS, it is flagged as +needing rewriting in Weblate. This way you can easily filter and edit +translations created by the developers. + +.. AUTOGENERATED END: weblate.flags.target_edit + +.. seealso:: + + :ref:`states` + +.. AUTOGENERATED START: weblate.flags.target_repo_update +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.flags.target_repo_update: + +Flag updated translations from repository as "Needs rewriting" +-------------------------------------------------------------- + +:Add-on ID: ``weblate.flags.target_repo_update`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-unit-post-sync` + +Whenever a string translation is changed from the VCS, it is flagged as needing +rewriting in Weblate. Especially useful if translation files are often updated +manually or by an external service. + +.. AUTOGENERATED END: weblate.flags.target_repo_update + +.. seealso:: + + :ref:`states` + +.. AUTOGENERATED START: weblate.generate.fill_read_only +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.generate.fill_read_only: + +Fill read-only strings with source +---------------------------------- + +.. versionadded:: 4.18 + +:Add-on ID: ``weblate.generate.fill_read_only`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update`, :ref:`addon-event-daily` + +Fills in translation of read-only strings with source string. + +.. AUTOGENERATED END: weblate.generate.fill_read_only + +.. AUTOGENERATED START: weblate.generate.generate +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.generate.generate: + +Statistics generator +-------------------- + +:Add-on ID: ``weblate.generate.generate`` +:Configuration: +--------------+---------------------------+--+ + | ``filename`` | Name of generated file | | + +--------------+---------------------------+--+ + | ``template`` | Content of generated file | | + +--------------+---------------------------+--+ + +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-pre-commit` + +Generates a file containing detailed info about the translation status. + +.. AUTOGENERATED END: weblate.generate.generate + +You can use a Django template in both filename and content, see :ref:`markup` +for a detailed markup description. + +For example generating a summary file for each translation: + +Name of generated file + ``locale/{{ language_code }}.json`` +Content + .. code-block:: json + + { + "language": "{{ language_code }}", + "strings": "{{ stats.all }}", + "translated": "{{ stats.translated }}", + "last_changed": "{{ stats.last_changed }}", + "last_author": "{{ stats.last_author }}", + } + + +.. seealso:: + + :ref:`markup` + +.. AUTOGENERATED START: weblate.generate.prefill +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.generate.prefill: + +Prefill translation with source +------------------------------- + +.. versionadded:: 4.11 + +:Add-on ID: ``weblate.generate.prefill`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update`, :ref:`addon-event-daily` + +Fills in translation strings with source string. + +.. AUTOGENERATED END: weblate.generate.prefill + +All untranslated strings in the component will be filled with the source +string, and marked as needing edit. Use this when you can not have empty +strings in the translation files. +.. AUTOGENERATED START: weblate.generate.pseudolocale +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.generate.pseudolocale: + +Pseudolocale generation +----------------------- + +.. versionadded:: 4.5 + +:Add-on ID: ``weblate.generate.pseudolocale`` +:Configuration: +----------------------+---------------------------+------------------------------------------------------------------------------------------+ + | ``source`` | Source strings | | + +----------------------+---------------------------+------------------------------------------------------------------------------------------+ + | ``target`` | Target translation | All strings in this translation will be overwritten | + +----------------------+---------------------------+------------------------------------------------------------------------------------------+ + | ``prefix`` | Prepended static text | | + +----------------------+---------------------------+------------------------------------------------------------------------------------------+ + | ``var_prefix`` | Prepended variable text | | + +----------------------+---------------------------+------------------------------------------------------------------------------------------+ + | ``suffix`` | Appended static text | | + +----------------------+---------------------------+------------------------------------------------------------------------------------------+ + | ``var_suffix`` | Appended variable text | | + +----------------------+---------------------------+------------------------------------------------------------------------------------------+ + | ``var_multiplier`` | Variable text multiplier | How many times to repeat the variable text depending on the length of the source string. | + +----------------------+---------------------------+------------------------------------------------------------------------------------------+ + | ``include_readonly`` | Include read-only strings | | + +----------------------+---------------------------+------------------------------------------------------------------------------------------+ + +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update`, :ref:`addon-event-daily` + +Generates a translation by adding prefix and suffix to source strings +automatically. + +.. AUTOGENERATED END: weblate.generate.pseudolocale + +Pseudolocales are useful to find strings that are not prepared for +localization. This is done by altering all translatable source strings +to make it easy to spot unaltered strings when running the application +in the pseudolocale language. + +Finding strings whose localized counterparts might not fit the layout +is also possible. + +Using the variable parts makes it possible to look for strings which might not +fit into the user interface after the localization - it extends the text based +on the source string length. The variable texts are repeated by length of the +text multiplied by the multiplier. For example ``Hello world`` with variable +text ``_`` and variable multiplier of 1 becomes ``Hello world___________`` - +the text is repeated once for each character in the source string. + +The strings will be generated using following pattern: + +:guilabel:`Prepended static text` +:guilabel:`Prepended variable text` +:guilabel:`Source string` +:guilabel:`Appended variable text` +:guilabel:`Appended static text` + +.. hint:: + + You can use real languages for testing, but there are dedicated + pseudolocales available in Weblate - `en_XA` and `ar_XB`. + +.. hint:: + + You can use this add-on to start translation to a new locale of an + existing language or similar language. + Once you add the translation to the component, follow to the add-on. + *Example:* If you have `fr` and want to start `fr_CA` translation, simply set + `fr` as the source, `fr_CA` as the target, and leave the prefix and suffix blank. + + Uninstall the add-on once you have the new translation filled to prevent Weblate + from changing the translations made after the copying. + + +.. AUTOGENERATED START: weblate.gettext.authors +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.gettext.authors: + +Contributors in comment +----------------------- + +:Add-on ID: ``weblate.gettext.authors`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-repository-pre-commit` + +Updates the comment part of the PO file header to include contributor names and +years of contributions. + +.. AUTOGENERATED END: weblate.gettext.authors + +The PO file header will look like this: + +.. code-block:: po + + # Michal Čihař , 2012, 2018, 2019, 2020. + # Pavel Borecki , 2018, 2019. + # Filip Hron , 2018, 2019. + # anonymous , 2019. + +.. AUTOGENERATED START: weblate.gettext.configure +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.gettext.configure: + +Update ALL_LINGUAS variable in the "configure" file +--------------------------------------------------- + +:Add-on ID: ``weblate.gettext.configure`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily`, :ref:`addon-event-repository-post-add` + +Updates the ALL_LINGUAS variable in "configure", "configure.in" or +"configure.ac" files, when a new translation is added. + +.. AUTOGENERATED END: weblate.gettext.configure + +Updates the ALL_LINGUAS variable in :file:`configure`, :file:`configure.in` or any +:file:`configure.ac` files, when a new translation is added. + +.. _addon-weblate.gettext.customize: + +Customize gettext output +------------------------ + +.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`. + +.. AUTOGENERATED START: weblate.gettext.linguas +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.gettext.linguas: + +Update LINGUAS file +------------------- + +:Add-on ID: ``weblate.gettext.linguas`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily`, :ref:`addon-event-repository-post-add` + +Updates the LINGUAS file when a new translation is added. + +.. AUTOGENERATED END: weblate.gettext.linguas +.. AUTOGENERATED START: weblate.gettext.mo +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.gettext.mo: + +Generate MO files +----------------- + +:Add-on ID: ``weblate.gettext.mo`` +:Configuration: +-----------+---------------------------------+----------------------------------------------------------------------------------+ + | ``path`` | Path of generated MO file | If not specified, the location of the PO file will be used. | + +-----------+---------------------------------+----------------------------------------------------------------------------------+ + | ``fuzzy`` | Include strings needing editing | Strings needing editing (fuzzy) are typically not ready for use as translations. | + +-----------+---------------------------------+----------------------------------------------------------------------------------+ + +:Triggers: :ref:`addon-event-repository-pre-commit` + +Automatically generates a MO file for every changed PO file. + +.. AUTOGENERATED END: weblate.gettext.mo + +The location of the generated MO file can be customized and the field for it uses :ref:`markup`. + +.. note:: + + If a translation is removed, its PO file will be deleted from the + repository, but the MO file generated by this add-on will not. The MO file + must be removed from the upstream manually. + + +.. AUTOGENERATED START: weblate.gettext.msgmerge +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.gettext.msgmerge: + +Update PO files to match POT (msgmerge) +--------------------------------------- + +.. versionchanged:: 5.13 + + :guilabel:`Settings` configuration has been moved to :ref:`file_format_params`. + +:Add-on ID: ``weblate.gettext.msgmerge`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-update` + +Updates all PO files (as configured by "File mask") to match the POT file (as +configured by "Template for new translations") using msgmerge. + +.. AUTOGENERATED END: weblate.gettext.msgmerge + +This add-on is essential when working with gettext PO files where the POT +(template) file is updated with new strings or changes to existing strings. +When the POT file is updated in the repository, this add-on automatically +merges those changes into all language PO files, ensuring that: + +* New translatable strings appear in all languages +* Removed strings are marked as obsolete +* Modified strings are marked as needing review (fuzzy) + +Most msgmerge command-line options can be set up through file format parameters +configuration. + +.. seealso:: + + * :ref:`component-filemask` + * :ref:`component-new_base` + * :program:`msgmerge` + * :ref:`faq-cleanup` + * :ref:`updating-target-files` + +.. AUTOGENERATED START: weblate.git.squash +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.git.squash: + +Squash Git commits +------------------ + +:Add-on ID: ``weblate.git.squash`` +:Configuration: +---------------------+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``squash`` | Commit squashing | .. list-table:: Available choices: | + | | | :width: 100% | + | | | | + | | | * - ``all`` | + | | | - All commits into one | + | | | * - ``language`` | + | | | - Per language | + | | | * - ``file`` | + | | | - Per file | + | | | * - ``author`` | + | | | - Per author | + +---------------------+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``append_trailers`` | Append trailers to squashed commit message | Trailer lines are lines that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit message, such as 'Co-authored-by: …'. | + +---------------------+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``commit_message`` | Commit message | This commit message will be used instead of the combined commit messages from the squashed commits. | + +---------------------+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-commit` + +Squash Git commits prior to pushing changes. + +.. AUTOGENERATED END: weblate.git.squash + +.. hint:: + + To avoid unnecessary conflicts, it is recommended to configure automatic + receiving of upstream changes by webhooks or API, see :ref:`update-vcs`. + +Git commits can be squashed prior to pushing changes +in one of the following modes: + +* All commits into one +* Per language +* Per file +* Per author + +Original commit messages are kept, but authorship is lost unless :guilabel:`Per author` is selected, or +the commit message is customized to include it. + +The original commit messages can optionally be overridden with a custom commit message. + +Trailers (commit lines like ``Co-authored-by: …``) can optionally be removed +from the original commit messages and appended to the end of the squashed +commit message. This also generates proper ``Co-authored-by:`` credit for every +translator. + +.. _addon-weblate.json.customize: + +Customize JSON output +--------------------- + +.. versionchanged:: 5.12 + + :guilabel:`Avoid spaces after separators` option added. + +.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`. + +.. AUTOGENERATED START: weblate.properties.sort +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.properties.sort: + +Format the Java properties file +------------------------------- + +:Add-on ID: ``weblate.properties.sort`` +:Configuration: +--------------------+-----------------------------------+--+ + | ``case_sensitive`` | Enable case-sensitive key sorting | | + +--------------------+-----------------------------------+--+ + +:Triggers: :ref:`addon-event-repository-pre-commit` + +Formats and sorts the Java properties file. + +.. AUTOGENERATED END: weblate.properties.sort + +* Consolidates newlines to Unix ones. +* Uppercase formatting of Unicode escape sequences (in case they are present). +* Strips blank lines and comments. +* Sorts the strings by the keys. +* Drops duplicate strings. + +.. AUTOGENERATED START: weblate.removal.comments +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.removal.comments: + +Stale comment removal +--------------------- + +:Add-on ID: ``weblate.removal.comments`` +:Configuration: +---------+--------------+--+ + | ``age`` | Days to keep | | + +---------+--------------+--+ + +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily` + +Set a timeframe for removal of comments. + +.. AUTOGENERATED END: weblate.removal.comments + +This can be useful to remove old +comments which might have become outdated. Use with care as comments +getting old does not mean they have lost their importance. + +.. AUTOGENERATED START: weblate.removal.suggestions +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.removal.suggestions: + +Stale suggestion removal +------------------------ + +:Add-on ID: ``weblate.removal.suggestions`` +:Configuration: +-----------+------------------+-------------------------------------------------------------------------+ + | ``age`` | Days to keep | | + +-----------+------------------+-------------------------------------------------------------------------+ + | ``votes`` | Voting threshold | Threshold for removal. This field has no effect with voting turned off. | + +-----------+------------------+-------------------------------------------------------------------------+ + +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-daily` + +Set a timeframe for removal of suggestions. + +.. AUTOGENERATED END: weblate.removal.suggestions + +Can be very useful in connection with suggestion voting +(see :ref:`peer-review`) to remove suggestions which +don't receive enough positive votes in a given timeframe. + +.. AUTOGENERATED START: weblate.resx.update +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.resx.update: + +Update RESX files +----------------- + +:Add-on ID: ``weblate.resx.update`` +:Configuration: `This add-on has no configuration.` +:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-update` + +Update all translation files to match the monolingual upstream base file. +Unused strings are removed, and new ones added as copies of the source string. + +.. AUTOGENERATED END: weblate.resx.update + +.. hint:: + + Use :ref:`addon-weblate.cleanup.generic` if you only want to remove stale + translation keys. + +.. seealso:: + + :ref:`faq-cleanup` + +.. AUTOGENERATED START: weblate.webhook.slack +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.webhook.slack: + +Slack Webhooks +-------------- + +.. versionadded:: 5.12 + +:Add-on ID: ``weblate.webhook.slack`` +:Configuration: +-----------------+---------------+----------------------------+ + | ``webhook_url`` | Webhook URL | | + +-----------------+---------------+----------------------------+ + | ``events`` | Change events | :ref:`addon-choice-events` | + +-----------------+---------------+----------------------------+ + +:Triggers: :ref:`addon-event-event-change` + +Sends notification to a Slack channel based on selected events. + +.. AUTOGENERATED END: weblate.webhook.slack + +.. warning:: + + The notification content might show HTML tags. This is a known issue that will be soon addressed; see https://github.com/WeblateOrg/weblate/issues/15056. + +.. hint:: + + To obtain a webhook URL, follow the steps outlined in the `Slack Incoming Webhooks documentation `_ + +.. AUTOGENERATED START: weblate.webhook.webhook +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-weblate.webhook.webhook: + +Webhook +------- + +.. versionadded:: 5.11 + +.. versionchanged:: 5.15 + + Compliance of the secret length with the specification is now validated. + +:Add-on ID: ``weblate.webhook.webhook`` +:Configuration: +-----------------+----------------+----------------------------------------------------------+ + | ``webhook_url`` | Webhook URL | | + +-----------------+----------------+----------------------------------------------------------+ + | ``secret`` | Webhook secret | The Standard Webhooks secret is a base64 encoded string. | + +-----------------+----------------+----------------------------------------------------------+ + | ``events`` | Change events | :ref:`addon-choice-events` | + +-----------------+----------------+----------------------------------------------------------+ + +:Triggers: :ref:`addon-event-event-change` + +Sends notifications to external services based on selected events, following +the Standard Webhooks specification. + +.. AUTOGENERATED END: weblate.webhook.webhook + +The request payload complies with the :ref:`schema-messaging` schema. +The OpenAPI description can also be found at ``/api/docs/``. +Sample request body: + +.. code-block:: json + + { + "change_id": 99, + "action": "Translation changed", + "timestamp": "2019-08-24T14:15:22Z", + "target": "Nazdar svete!", + "old": "Nazdar!", + "source": "Hello, world", + "url": "/translate/project-slug/component-slug/cs/?checksum=46add148a53cab6f", + "author": "author-username", + "user": "user-username", + "project": "project-slug", + "component": "component-slug", + "translation": "cs" + } + +Sample request body with categories: + +.. code-block:: json + + { + "change_id": 8910, + "action": "Component renamed", + "timestamp": "2025-06-11T07:15:09Z", + "target": ["new-name"], + "old": ["component-slug"], + "url": "/projects/project-slug/parent-category/child-category/sub-category/component-slug/", + "user": "testuser", + "project": "project-slug", + "component": "component-slug", + "category": [ + "sub-category", + "child-category", + "parent-category" + ] + } + +Sample request headers: + +.. code-block:: json + + { + "webhook-id": "7f1c5477f6275a69af7b83236c20cb1a", + "webhook-timestamp": "1748505623.044281", + "webhook-signature": "v1,Ceo5qEr07ixe2NLpvHk3FH9bwy/WavXrAFQ/9tdO6mc=" + } + +The ``webhook-signature`` is a space separated list of HMAC signatures generated using the ``secret`` string, +the request payload, the ``webhook-timestamp``, and the ``webhook-id``. This ensures the authenticity +and integrity of the webhook request. + +The provided ``secret`` is a base64 encoded string between 24 bytes (192 bits) +and 64 bytes (512 bits). It can be prefixed with ``whsec_`` for easy +identification. + +To verify a request, you can use the ``Webhook.verify`` method from the ``standardwebhooks`` library +or an implementation of the "Standard Webhooks Specification". + + +.. seealso:: + + * `Standard Webhooks Specification `_ + * :ref:`schema-messaging` + * `Python library for Standard Webhooks `_ + + +.. Depreciated Addons +.. _addon-weblate.xml.customize: + +Customize XML output +-------------------- + +.. versionadded:: 4.15 + +.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`. + +.. _addon-weblate.yaml.customize: + +Customize YAML output +--------------------- + +.. versionremoved:: 5.13 Replaced by :ref:`file_format_params`. + +Common add-on parameters +++++++++++++++++++++++++ + +.. AUTOGENERATED START: addon-parameters +.. This section is automatically generated by `./manage.py list_addons`. Do not edit manually. + +.. _addon-choice-engines: + +Machine translation engines +--------------------------- + +.. list-table:: Available choices: + :width: 100% + + * - ``alibaba`` + - Alibaba + * - ``aws`` + - Amazon Translate + * - ``anthropic`` + - Anthropic + * - ``apertium-apy`` + - Apertium APy + * - ``microsoft-translator`` + - Azure AI Translator + * - ``azure-openai`` + - Azure OpenAI + * - ``baidu`` + - Baidu + * - ``cyrtranslit`` + - CyrTranslit + * - ``deepl`` + - DeepL + * - ``glosbe`` + - Glosbe + * - ``google-translate-api-v3`` + - Google Cloud Translation Advanced + * - ``google-translate`` + - Google Cloud Translation Basic + * - ``libretranslate`` + - LibreTranslate + * - ``modernmt`` + - ModernMT + * - ``mymemory`` + - MyMemory + * - ``netease-sight`` + - Netease Sight + * - ``ollama`` + - Ollama + * - ``openai`` + - OpenAI + * - ``sap-translation-hub`` + - SAP Translation Hub + * - ``systran`` + - Systran + * - ``weblate`` + - Weblate + * - ``weblate-translation-memory`` + - Weblate Translation Memory + * - ``yandex`` + - Yandex + * - ``yandex-v2`` + - Yandex v2 + * - ``youdao-zhiyun`` + - Youdao Zhiyun + * - ``tmserver`` + - tmserver + +.. _addon-choice-file_format: + +File format +----------- + +.. list-table:: Available choices: + :width: 100% + + * - ``apple-xliff`` + - XLIFF 1.2 with Apple extensions + * - ``appstore`` + - App store metadata files + * - ``arb`` + - ARB file + * - ``aresource`` + - Android String Resource + * - ``asciidoc`` + - AsciiDoc file + * - ``ass`` + - Advanced SubStation Alpha subtitle file + * - ``catkeys`` + - Haiku catkeys + * - ``cmp-resource`` + - Compose Multiplatform Resource + * - ``csv`` + - CSV file + * - ``csv-multi`` + - Multivalue CSV file + * - ``csv-simple`` + - Simple CSV file + * - ``dokuwiki`` + - DokuWiki text file + * - ``dtd`` + - DTD file + * - ``flatxml`` + - Flat XML file + * - ``fluent`` + - Fluent file + * - ``formatjs`` + - Format.JS JSON file + * - ``go-i18n-json`` + - go-i18n v1 JSON file + * - ``go-i18n-json-v2`` + - go-i18n v2 JSON file + * - ``go-i18n-toml`` + - go-i18n TOML file + * - ``gotext`` + - gotext JSON file + * - ``gwt`` + - GWT properties + * - ``html`` + - HTML file + * - ``i18next`` + - i18next JSON file v3 + * - ``i18nextv4`` + - i18next JSON file v4 + * - ``idml`` + - IDML file + * - ``ini`` + - INI file + * - ``islu`` + - Inno Setup INI file + * - ``joomla`` + - Joomla language file + * - ``json`` + - JSON file + * - ``json-nested`` + - JSON nested structure file + * - ``laravel`` + - Laravel PHP strings + * - ``markdown`` + - Markdown file + * - ``mediawiki`` + - MediaWiki text file + * - ``mi18n-lang`` + - @draggable/i18n lang file + * - ``moko-resource`` + - Mobile Kotlin Resource + * - ``nextcloud-json`` + - Nextcloud JSON file + * - ``odf`` + - OpenDocument file + * - ``php`` + - PHP strings + * - ``plainxliff`` + - XLIFF 1.2 translation file + * - ``po`` + - gettext PO file + * - ``po-mono`` + - gettext PO file (monolingual) + * - ``poxliff`` + - XLIFF 1.2 with gettext extensions + * - ``properties`` + - Java Properties + * - ``rc`` + - RC file + * - ``resjson`` + - RESJSON file + * - ``resourcedictionary`` + - ResourceDictionary file + * - ``resx`` + - .NET resource file + * - ``ruby-yaml`` + - Ruby YAML file + * - ``srt`` + - SubRip subtitle file + * - ``ssa`` + - SubStation Alpha subtitle file + * - ``strings`` + - iOS strings + * - ``stringsdict`` + - Stringsdict file + * - ``sub`` + - MicroDVD subtitle file + * - ``tbx`` + - TermBase eXchange file + * - ``toml`` + - TOML file + * - ``ts`` + - Qt Linguist translation file + * - ``txt`` + - Plain text file + * - ``webextension`` + - WebExtension JSON file + * - ``wxl`` + - WixLocalization file + * - ``xliff`` + - XLIFF 1.2 with placeables support + * - ``xliff2`` + - XLIFF 2.0 translation file + * - ``xliff2-placeables`` + - XLIFF 2.0 translation file with placeables support + * - ``xlsx`` + - Excel Open XML + * - ``xwiki-fullpage`` + - XWiki Full Page + * - ``xwiki-java-properties`` + - XWiki Java Properties + * - ``xwiki-page-properties`` + - XWiki Page Properties + * - ``yaml`` + - YAML file + +.. _addon-choice-events: + +Change events +------------- + +.. list-table:: Available choices: + :width: 100% + + * - ``0`` + - Resource updated + * - ``1`` + - Translation completed + * - ``2`` + - Translation changed + * - ``3`` + - Comment added + * - ``4`` + - Suggestion added + * - ``5`` + - Translation added + * - ``6`` + - Automatically translated + * - ``7`` + - Suggestion accepted + * - ``8`` + - Translation reverted + * - ``9`` + - Translation uploaded + * - ``13`` + - Source string added + * - ``14`` + - Component locked + * - ``15`` + - Component unlocked + * - ``17`` + - Changes committed + * - ``18`` + - Changes pushed + * - ``19`` + - Repository reset + * - ``20`` + - Repository merged + * - ``21`` + - Repository rebased + * - ``22`` + - Repository merge failed + * - ``23`` + - Repository rebase failed + * - ``24`` + - Parsing failed + * - ``25`` + - Translation removed + * - ``26`` + - Suggestion removed + * - ``27`` + - Translation replaced + * - ``28`` + - Repository push failed + * - ``29`` + - Suggestion removed during cleanup + * - ``30`` + - Source string changed + * - ``31`` + - String added + * - ``32`` + - Bulk status changed + * - ``33`` + - Visibility changed + * - ``34`` + - User added + * - ``35`` + - User removed + * - ``36`` + - Translation approved + * - ``37`` + - Marked for edit + * - ``38`` + - Component removed + * - ``39`` + - Project removed + * - ``41`` + - Project renamed + * - ``42`` + - Component renamed + * - ``43`` + - Moved component + * - ``45`` + - Contributor joined + * - ``46`` + - Announcement posted + * - ``47`` + - Alert triggered + * - ``48`` + - Language added + * - ``49`` + - Language requested + * - ``50`` + - Project created + * - ``51`` + - Component created + * - ``52`` + - User invited + * - ``53`` + - Repository notification received + * - ``54`` + - Translation replaced file by upload + * - ``55`` + - License changed + * - ``56`` + - Contributor license agreement changed + * - ``57`` + - Screenshot added + * - ``58`` + - Screenshot uploaded + * - ``59`` + - String updated in the repository + * - ``60`` + - Add-on installed + * - ``61`` + - Add-on configuration changed + * - ``62`` + - Add-on uninstalled + * - ``63`` + - String removed + * - ``64`` + - Comment removed + * - ``65`` + - Comment resolved + * - ``66`` + - Explanation updated + * - ``67`` + - Category removed + * - ``68`` + - Category renamed + * - ``69`` + - Category moved + * - ``70`` + - Saving string failed + * - ``71`` + - String added in the repository + * - ``72`` + - String updated in the upload + * - ``73`` + - String added in the upload + * - ``74`` + - Translation updated by source upload + * - ``75`` + - Component translation completed + * - ``76`` + - Applied enforced check + * - ``77`` + - Propagated change + * - ``78`` + - File uploaded + * - ``79`` + - Extra flags updated + * - ``80`` + - Font uploaded + * - ``81`` + - Font changed + * - ``82`` + - Font removed + * - ``83`` + - Forced synchronization of translations + * - ``84`` + - Forced rescan of translations + * - ``85`` + - Screenshot removed + * - ``86`` + - Label added + * - ``87`` + - Label removed + * - ``88`` + - Repository cleanup + * - ``89`` + - Source string added in the upload + * - ``90`` + - Source string added in the repository + + +.. AUTOGENERATED END: addon-parameters diff --git a/docs/snippets/change-events.rst b/docs/snippets/change-events.rst deleted file mode 100644 index daf2667ce2f9..000000000000 --- a/docs/snippets/change-events.rst +++ /dev/null @@ -1,173 +0,0 @@ -.. list-table:: Available choices: - :width: 100% - - * - ``0`` - - Resource updated - * - ``1`` - - Translation completed - * - ``2`` - - Translation changed - * - ``3`` - - Comment added - * - ``4`` - - Suggestion added - * - ``5`` - - Translation added - * - ``6`` - - Automatically translated - * - ``7`` - - Suggestion accepted - * - ``8`` - - Translation reverted - * - ``9`` - - Translation uploaded - * - ``13`` - - Source string added - * - ``14`` - - Component locked - * - ``15`` - - Component unlocked - * - ``17`` - - Changes committed - * - ``18`` - - Changes pushed - * - ``19`` - - Repository reset - * - ``20`` - - Repository merged - * - ``21`` - - Repository rebased - * - ``22`` - - Repository merge failed - * - ``23`` - - Repository rebase failed - * - ``24`` - - Parsing failed - * - ``25`` - - Translation removed - * - ``26`` - - Suggestion removed - * - ``27`` - - Translation replaced - * - ``28`` - - Repository push failed - * - ``29`` - - Suggestion removed during cleanup - * - ``30`` - - Source string changed - * - ``31`` - - String added - * - ``32`` - - Bulk status changed - * - ``33`` - - Visibility changed - * - ``34`` - - User added - * - ``35`` - - User removed - * - ``36`` - - Translation approved - * - ``37`` - - Marked for edit - * - ``38`` - - Component removed - * - ``39`` - - Project removed - * - ``41`` - - Project renamed - * - ``42`` - - Component renamed - * - ``43`` - - Moved component - * - ``45`` - - Contributor joined - * - ``46`` - - Announcement posted - * - ``47`` - - Alert triggered - * - ``48`` - - Language added - * - ``49`` - - Language requested - * - ``50`` - - Project created - * - ``51`` - - Component created - * - ``52`` - - User invited - * - ``53`` - - Repository notification received - * - ``54`` - - Translation replaced file by upload - * - ``55`` - - License changed - * - ``56`` - - Contributor license agreement changed - * - ``57`` - - Screenshot added - * - ``58`` - - Screenshot uploaded - * - ``59`` - - String updated in the repository - * - ``60`` - - Add-on installed - * - ``61`` - - Add-on configuration changed - * - ``62`` - - Add-on uninstalled - * - ``63`` - - String removed - * - ``64`` - - Comment removed - * - ``65`` - - Comment resolved - * - ``66`` - - Explanation updated - * - ``67`` - - Category removed - * - ``68`` - - Category renamed - * - ``69`` - - Category moved - * - ``70`` - - Saving string failed - * - ``71`` - - String added in the repository - * - ``72`` - - String updated in the upload - * - ``73`` - - String added in the upload - * - ``74`` - - Translation updated by source upload - * - ``75`` - - Component translation completed - * - ``76`` - - Applied enforced check - * - ``77`` - - Propagated change - * - ``78`` - - File uploaded - * - ``79`` - - Extra flags updated - * - ``80`` - - Font uploaded - * - ``81`` - - Font changed - * - ``82`` - - Font removed - * - ``83`` - - Forced synchronization of translations - * - ``84`` - - Forced rescan of translations - * - ``85`` - - Screenshot removed - * - ``86`` - - Label added - * - ``87`` - - Label removed - * - ``88`` - - Repository cleanup - * - ``89`` - - Source string added in the upload - * - ``90`` - - Source string added in the repository diff --git a/docs/snippets/check-flags-autogenerated.rst b/docs/snippets/check-flags-autogenerated.rst new file mode 100644 index 000000000000..d8fe7d59e188 --- /dev/null +++ b/docs/snippets/check-flags-autogenerated.rst @@ -0,0 +1,304 @@ +``dos-eol`` + Uses DOS end-of-line markers instead of Unix ones (``\r\n`` instead of ``\n``). +``read-only`` + The string is read-only and should not be edited in Weblate, see :ref:`read-only-strings`. +``terminology`` + Used in :ref:`glossary`. Copies the string into all glossary languages so it can be used consistently in all translations. Also useful in combination with ``read-only``, for example in product names. +``priority:N`` + Priority of the string. Higher priority strings are presented first for translation. + The default priority is 100, the higher priority a string has, the earlier it is + offered for translation. +``max-length:N`` + Limit the maximal length for a string to N characters, see :ref:`check-max-length`. +``xml-text`` + Treat text as XML document, affects :ref:`check-xml-invalid` and :ref:`check-xml-tags`. +``font-family:NAME`` + Define font-family for rendering checks, see :ref:`fonts`. +``font-weight:WEIGHT`` + Define font-weight for rendering checks, see :ref:`fonts`. +``font-size:SIZE`` + Define font-size for rendering checks, see :ref:`fonts`. +``font-spacing:SPACING`` + Define letter spacing for rendering checks, see :ref:`fonts`. +``icu-flags:FLAGS`` + Define flags for customizing the behavior of the :ref:`check-icu-message-format` quality check. +``icu-tag-prefix:PREFIX`` + Set a required prefix for XML tags for the :ref:`check-icu-message-format` quality check. +``placeholders:NAME:NAME2:...`` + Placeholder strings expected in translation, see :ref:`check-placeholders`. +``replacements:FROM:TO:FROM2:TO2...`` + Replacements to perform when checking resulting text parameters (for + example in :ref:`check-max-size` or :ref:`check-max-length`). The typical + use case for this is to expand placeables to ensure that the text fits even + with long values, for example: ``replacements:%s:"John Doe"``. +``variants:SOURCE`` + Mark this string as a variant of string with matching source. See :ref:`variants`. +``regex:REGEX`` + Regular expression to match translation, see :ref:`check-regex`. +``discard:NAME`` + Discards flag defined on a higher level. +``forbidden`` + Indicates forbidden translation in a glossary, see :ref:`glossary-forbidden`. +``strict-same`` + Make the :ref:`check-same` avoid using the built-in words exceptions. +``strict-format`` + Make format checks enforce using format even for plural forms with a single value, see :ref:`check-formats`. +``case-insensitive`` + Adjust checks behavior to be case-insensitive. Currently affects only :ref:`check-placeholders` quality check. + +.. AUTOGENERATED START: check-flags-enables +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +``bbcode-text`` + Treat a text as an Bulletin Board Code (BBCode) document, affects :ref:`check-same`. + Enables the :ref:`check-bbcode` quality check. +``check-glossary`` + Enables the :ref:`check-check-glossary` quality check. +``fluent-parts`` + Enables the :ref:`check-fluent-parts` quality check. +``fluent-references`` + Enables the :ref:`check-fluent-references` quality check. +``fluent-target-inner-html`` + Enables the :ref:`check-fluent-target-inner-html` quality check. +``fluent-target-syntax`` + Enables the :ref:`check-fluent-target-syntax` quality check. +``angularjs-format`` + Enables the :ref:`check-angularjs-format` quality check. +``automattic-components-format`` + Enables the :ref:`check-automattic-components-format` quality check. +``c-format`` + Enables the :ref:`check-c-format` quality check. +``c-sharp-format`` + Enables the :ref:`check-c-sharp-format` quality check. +``es-format`` + Enables the :ref:`check-es-format` quality check. +``i18next-interpolation`` + Enables the :ref:`check-i18next-interpolation` quality check. +``icu-message-format`` + Enables the :ref:`check-icu-message-format` and :ref:`check-icu-message-format-syntax` quality checks. +``java-printf-format`` + Enables the :ref:`check-java-printf-format` quality check. +``java-format`` + Enables the :ref:`check-java-format` quality check. +``javascript-format`` + Enables the :ref:`check-javascript-format` quality check. +``laravel-format`` + Enables the :ref:`check-laravel-format` quality check. +``lua-format`` + Enables the :ref:`check-lua-format` quality check. +``object-pascal-format`` + Enables the :ref:`check-object-pascal-format` quality check. +``percent-placeholders`` + Enables the :ref:`check-percent-placeholders` quality check. +``perl-brace-format`` + Enables the :ref:`check-perl-brace-format` quality check. +``perl-format`` + Enables the :ref:`check-perl-format` quality check. +``php-format`` + Enables the :ref:`check-php-format` quality check. +``python-brace-format`` + Enables the :ref:`check-python-brace-format` quality check. +``python-format`` + Enables the :ref:`check-python-format` quality check. +``qt-format`` + Enables the :ref:`check-qt-format` quality check. +``qt-plural-format`` + Enables the :ref:`check-qt-plural-format` quality check. +``ruby-format`` + Enables the :ref:`check-ruby-format` quality check. +``scheme-format`` + Enables the :ref:`check-scheme-format` quality check. +``vue-format`` + Enables the :ref:`check-vue-format` quality check. +``rst-text`` + Treat a text as an reStructuredText document, affects :ref:`check-same`. + Enables the :ref:`check-rst-references` and :ref:`check-rst-syntax` quality checks. +``md-text`` + Treat a text as a Markdown document, and provide Markdown syntax highlighting on the translation text area. + Enables the :ref:`check-md-link`, :ref:`check-md-reflink` and :ref:`check-md-syntax` quality checks. +``max-length`` + Enables the :ref:`check-max-length` quality check. +``max-size`` + Enables the :ref:`check-max-size` quality check. +``placeholders`` + Enables the :ref:`check-placeholders` quality check. +``regex`` + Enables the :ref:`check-regex` quality check. +``safe-html`` + Enables the :ref:`check-safe-html` quality check. +``url`` + The string should consist of only a URL. + Enables the :ref:`check-url` quality check. +``fluent-source-inner-html`` + Enables the :ref:`check-fluent-source-inner-html` quality check. +``fluent-source-syntax`` + Enables the :ref:`check-fluent-source-syntax` quality check. + +.. AUTOGENERATED END: check-flags-enables + +``ignore-all-checks`` + Ignore all quality checks. + +.. AUTOGENERATED START: check-flags-ignores +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +``ignore-bbcode`` + Skip the :ref:`check-bbcode` quality check. +``ignore-xml-chars-around-tags`` + Skip the :ref:`check-xml-chars-around-tags` quality check. +``ignore-duplicate`` + Skip the :ref:`check-duplicate` quality check. +``ignore-check-glossary`` + Skip the :ref:`check-check-glossary` quality check. +``ignore-double-space`` + Skip the :ref:`check-double-space` quality check. +``ignore-fluent-parts`` + Skip the :ref:`check-fluent-parts` quality check. +``ignore-fluent-references`` + Skip the :ref:`check-fluent-references` quality check. +``ignore-fluent-target-inner-html`` + Skip the :ref:`check-fluent-target-inner-html` quality check. +``ignore-fluent-target-syntax`` + Skip the :ref:`check-fluent-target-syntax` quality check. +``ignore-angularjs-format`` + Skip the :ref:`check-angularjs-format` quality check. +``ignore-automattic-components-format`` + Skip the :ref:`check-automattic-components-format` quality check. +``ignore-c-format`` + Skip the :ref:`check-c-format` quality check. +``ignore-c-sharp-format`` + Skip the :ref:`check-c-sharp-format` quality check. +``ignore-es-format`` + Skip the :ref:`check-es-format` quality check. +``ignore-i18next-interpolation`` + Skip the :ref:`check-i18next-interpolation` quality check. +``ignore-icu-message-format`` + Skip the :ref:`check-icu-message-format` quality check. +``ignore-java-printf-format`` + Skip the :ref:`check-java-printf-format` quality check. +``ignore-java-format`` + Skip the :ref:`check-java-format` quality check. +``ignore-javascript-format`` + Skip the :ref:`check-javascript-format` quality check. +``ignore-laravel-format`` + Skip the :ref:`check-laravel-format` quality check. +``ignore-lua-format`` + Skip the :ref:`check-lua-format` quality check. +``ignore-object-pascal-format`` + Skip the :ref:`check-object-pascal-format` quality check. +``ignore-percent-placeholders`` + Skip the :ref:`check-percent-placeholders` quality check. +``ignore-perl-brace-format`` + Skip the :ref:`check-perl-brace-format` quality check. +``ignore-perl-format`` + Skip the :ref:`check-perl-format` quality check. +``ignore-php-format`` + Skip the :ref:`check-php-format` quality check. +``ignore-python-brace-format`` + Skip the :ref:`check-python-brace-format` quality check. +``ignore-python-format`` + Skip the :ref:`check-python-format` quality check. +``ignore-qt-format`` + Skip the :ref:`check-qt-format` quality check. +``ignore-qt-plural-format`` + Skip the :ref:`check-qt-plural-format` quality check. +``ignore-ruby-format`` + Skip the :ref:`check-ruby-format` quality check. +``ignore-scheme-format`` + Skip the :ref:`check-scheme-format` quality check. +``ignore-vue-format`` + Skip the :ref:`check-vue-format` quality check. +``ignore-translated`` + Skip the :ref:`check-translated` quality check. +``ignore-inconsistent`` + Skip the :ref:`check-inconsistent` quality check. +``ignore-rst-references`` + Skip the :ref:`check-rst-references` quality check. +``ignore-kashida`` + Skip the :ref:`check-kashida` quality check. +``ignore-md-link`` + Skip the :ref:`check-md-link` quality check. +``ignore-md-reflink`` + Skip the :ref:`check-md-reflink` quality check. +``ignore-md-syntax`` + Skip the :ref:`check-md-syntax` quality check. +``ignore-max-length`` + Skip the :ref:`check-max-length` quality check. +``ignore-max-size`` + Skip the :ref:`check-max-size` quality check. +``ignore-escaped-newline`` + Skip the :ref:`check-escaped-newline` quality check. +``ignore-end-colon`` + Skip the :ref:`check-end-colon` quality check. +``ignore-end-ellipsis`` + Skip the :ref:`check-end-ellipsis` quality check. +``ignore-end-exclamation`` + Skip the :ref:`check-end-exclamation` quality check. +``ignore-end-stop`` + Skip the :ref:`check-end-stop` quality check. +``ignore-end-interrobang`` + Skip the :ref:`check-end-interrobang` quality check. +``ignore-end-question`` + Skip the :ref:`check-end-question` quality check. +``ignore-end-semicolon`` + Skip the :ref:`check-end-semicolon` quality check. +``ignore-newline-count`` + Skip the :ref:`check-newline-count` quality check. +``ignore-plurals`` + Skip the :ref:`check-plurals` quality check. +``ignore-multiple-capital`` + Skip the :ref:`check-multiple-capital` quality check. +``ignore-kabyle-characters`` + Skip the :ref:`check-kabyle-characters` quality check. +``ignore-placeholders`` + Skip the :ref:`check-placeholders` quality check. +``ignore-prohibited-initial-character`` + Skip the :ref:`check-prohibited-initial-character` quality check. +``ignore-punctuation-spacing`` + Skip the :ref:`check-punctuation-spacing` quality check. +``ignore-regex`` + Skip the :ref:`check-regex` quality check. +``ignore-rst-syntax`` + Skip the :ref:`check-rst-syntax` quality check. +``ignore-reused`` + Skip the :ref:`check-reused` quality check. +``ignore-same-plurals`` + Skip the :ref:`check-same-plurals` quality check. +``ignore-begin-newline`` + Skip the :ref:`check-begin-newline` quality check. +``ignore-begin-space`` + Skip the :ref:`check-begin-space` quality check. +``ignore-end-newline`` + Skip the :ref:`check-end-newline` quality check. +``ignore-end-space`` + Skip the :ref:`check-end-space` quality check. +``ignore-same`` + Skip the :ref:`check-same` quality check. +``ignore-safe-html`` + Skip the :ref:`check-safe-html` quality check. +``ignore-url`` + Skip the :ref:`check-url` quality check. +``ignore-xml-tags`` + Skip the :ref:`check-xml-tags` quality check. +``ignore-xml-invalid`` + Skip the :ref:`check-xml-invalid` quality check. +``ignore-zero-width-space`` + Skip the :ref:`check-zero-width-space` quality check. +``ignore-ellipsis`` + Skip the :ref:`check-ellipsis` quality check. +``ignore-fluent-source-inner-html`` + Skip the :ref:`check-fluent-source-inner-html` quality check. +``ignore-fluent-source-syntax`` + Skip the :ref:`check-fluent-source-syntax` quality check. +``ignore-icu-message-format`` + Skip the :ref:`check-icu-message-format-syntax` quality check. +``ignore-long-untranslated`` + Skip the :ref:`check-long-untranslated` quality check. +``ignore-multiple-failures`` + Skip the :ref:`check-multiple-failures` quality check. +``ignore-unnamed-format`` + Skip the :ref:`check-unnamed-format` quality check. +``ignore-optional-plural`` + Skip the :ref:`check-optional-plural` quality check. + +.. AUTOGENERATED END: check-flags-ignores diff --git a/docs/snippets/checks-autogenerated.rst b/docs/snippets/checks-autogenerated.rst new file mode 100644 index 000000000000..14c922b4952b --- /dev/null +++ b/docs/snippets/checks-autogenerated.rst @@ -0,0 +1,2529 @@ +Translation checks +------------------ + +Executed upon every translation change, helping translators maintain +good quality translations. + +.. AUTOGENERATED START: check-bbcode +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-bbcode: + +BBCode markup +~~~~~~~~~~~~~ + +.. versionchanged:: 5.10 + + This checks no longer relies on unreliable automatic detection, it now needs to be turned on using the ``bbcode-text`` flag. + +:Summary: BBCode in translation does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.markup.BBCodeCheck`` +:Check identifier: ``bbcode`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``bbcode-text`` +:Flag to ignore: ``ignore-bbcode`` + +.. AUTOGENERATED END: check-bbcode + +BBCode represents simple markup, like for example highlighting important parts of a +message in bold font, or italics. + +This check ensures they are also found in translation. + +.. note:: + + The method for detecting BBCode is currently quite simple so this check + might produce false positives. + +.. AUTOGENERATED START: check-xml-chars-around-tags +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-xml-chars-around-tags: + +Chars around XML tags +~~~~~~~~~~~~~~~~~~~~~ + +:Summary: Characters surrounding XML tags in translation do not align with source. +:Scope: translated strings +:Check class: ``weblate.checks.markup.XMLCharsAroundTagsCheck`` +:Check identifier: ``xml-chars-around-tags`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-xml-chars-around-tags`` + +.. AUTOGENERATED END: check-xml-chars-around-tags + +Checks that the characters surrounding an XML tag are consistent between both +source and translation. Ensures letters are not replaced with non-letters, and vice versa. + +.. note:: + + This check is disabled by the ``safe-html`` flag as the HTML cleanup done by + it can produce HTML markup which is not valid XML. + +.. AUTOGENERATED START: check-duplicate +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-duplicate: + +Consecutive duplicated words +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.1 + +:Summary: Text contains the same word twice in a row. +:Scope: translated strings +:Check class: ``weblate.checks.duplicate.DuplicateCheck`` +:Check identifier: ``duplicate`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-duplicate`` + +.. AUTOGENERATED END: check-duplicate + +Checks that no consecutive duplicate words occur in a translation. This usually +indicates a mistake in the translation. + +.. hint:: + + This check includes language specific rules to avoid false positives. In + case it triggers falsely in your case, let us know. See :ref:`report-issue`. + + +.. AUTOGENERATED START: check-check-glossary +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-check-glossary: + +Does not follow glossary +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.5 + +:Summary: The translation does not follow terms defined in a glossary. +:Scope: translated strings +:Check class: ``weblate.checks.glossary.GlossaryCheck`` +:Check identifier: ``check_glossary`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``check-glossary`` +:Flag to ignore: ``ignore-check-glossary`` + +.. AUTOGENERATED END: check-check-glossary + +This check has to be turned on using ``check-glossary`` flag (see +:ref:`custom-checks`). Please consider following prior to enabling it: + +* It does exact string matching, the glossary is expected to contain terms in all variants. +* Checking each string against glossary is expensive, it will slow down any operation in Weblate which involves running checks like importing strings or translating. +* It also utilizes untranslatable glossary terms in :ref:`check-same`. + +.. seealso:: + + * :ref:`glossary` + * :ref:`custom-checks` + * :ref:`component-check_flags` + + +.. AUTOGENERATED START: check-double-space +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-double-space: + +Double space +~~~~~~~~~~~~ + +:Summary: Translation contains double space. +:Scope: translated strings +:Check class: ``weblate.checks.chars.DoubleSpaceCheck`` +:Check identifier: ``double_space`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-double-space`` + +.. AUTOGENERATED END: check-double-space + +Checks that double space is present in translation to avoid false positives on other space-related checks. + +Check is false when double space is found in source meaning double space is intentional. + + +.. AUTOGENERATED START: check-fluent-parts +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-fluent-parts: + +Fluent parts +~~~~~~~~~~~~ + +.. versionadded:: 5.0 + +:Summary: Fluent parts should match. +:Scope: translated strings +:Check class: ``weblate.checks.fluent.parts.FluentPartsCheck`` +:Check identifier: ``fluent-parts`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`fluent` +:Flag to enable: ``fluent-parts`` +:Flag to ignore: ``ignore-fluent-parts`` + +.. AUTOGENERATED END: check-fluent-parts + +Each Fluent Message can have an optional value (the main text content), and +optional attributes, each of which is a "part" of the Message. In Weblate, all +these parts appear within the same block, using Fluent-like syntax to specify +the attributes. For example: + +.. code-block:: text + + This is the Message value + .title = This is the title attribute + .alt = This is the alt attribute + +This check ensures that the translated Message also has a value if the source +Message has one, or no value if the source has none. This also checks that the +same attributes used in the source Message also appear in the translation, with +no additions. + +.. note:: + + This check is not applied to Fluent Terms since Terms always have a value, and + Term attributes tend to be locale-specific (used for grammar rules, etc.), and + are not expected to appear in all translations. + +.. seealso:: + + `Fluent Attributes `_ + + +.. AUTOGENERATED START: check-fluent-references +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-fluent-references: + +Fluent references +~~~~~~~~~~~~~~~~~ + +.. versionadded:: 5.0 + +:Summary: Fluent references should match. +:Scope: translated strings +:Check class: ``weblate.checks.fluent.references.FluentReferencesCheck`` +:Check identifier: ``fluent-references`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`fluent` +:Flag to enable: ``fluent-references`` +:Flag to ignore: ``ignore-fluent-references`` + +.. AUTOGENERATED END: check-fluent-references + +A Fluent Message or Term can reference another Message, Term, Attribute, or a +variable. For example: + +.. code-block:: text + + Here is a { message }, a { message.attribute } a { -term } and a { $variable }. + Within a function { NUMBER($num, minimumFractionDigits: 2) } + +Generally, translated Messages or Terms are expected to contain the same +references as the source, although not necessarily in the same order of +appearance. So this check ensures that translations use the same references in +their value as the source value, the same number of times, and with no +additions. For Messages, this will also check that each Attribute in the +translation uses the same references as the matching Attribute in the source. + +When the source or translation contains Fluent Select Expressions, then each +possible variant in the source must be matched with at least one variant in the +translation with the same references, and vice versa. + +Moreover, if a variable reference appears both in the Select Expression's +selector and within one of its variants, then all variants may also be +considered as if they also contain that reference. The assumption being that the +variant's key may have made the reference redundant for that variant. For +example: + +.. code-block:: text + + { $num -> + [one] an apple + *[other] { $num } apples + } + +Here, for the purposes of this check, the ``[one]`` variant will also be +considered to contain the ``$num`` reference. + +However, a reference within the Select Expression's selector, which can only be +a variable of a Term Attribute in Fluent's syntax, will not by itself count as a +required reference because they do not form the actual text content of the +string that the end-user will see, and the presence of a Select Expression is +considered locale-specific. For example: + +.. code-block:: text + + { -term.starts-with-vowel -> + [yes] an { -term } + *[no] a { -term } + } + +Here a reference to ``-term.starts-with-vowel`` is not expected to appear in +translations, but a reference to ``-term`` is. + +.. seealso:: + + `Fluent Variables `_ + `Fluent Message and Term references `_ + `Fluent Select Expressions `_ + + +.. AUTOGENERATED START: check-fluent-target-inner-html +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-fluent-target-inner-html: + +Fluent translation inner HTML +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 5.0 + +:Summary: Fluent target should be valid inner HTML that matches. +:Scope: translated strings +:Check class: ``weblate.checks.fluent.inner_html.FluentTargetInnerHTMLCheck`` +:Check identifier: ``fluent-target-inner-html`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`fluent` +:Flag to enable: ``fluent-target-inner-html`` +:Flag to ignore: ``ignore-fluent-target-inner-html`` + +.. AUTOGENERATED END: check-fluent-target-inner-html + +This check will verify that the translated value of a Message or Term contains +the same HTML elements as the source value. + +First, if the source value fails the :ref:`check-fluent-source-inner-html` +check, then this check will do nothing. Otherwise, the translated value will +also be checked under the same conditions. + +Second, the HTML elements found in the translated value will be compared against +the HTML elements found in the source value. Two elements will match if they +share the exact same tag name, the exact same attributes and values, and all +their ancestors match in the same way. This check will ensure that all the +elements in the source appear somewhere in the translation, with the same +*number* of appearances, and with no additional elements added. When there are +multiple elements in the value, they need not appear in the same order in the +translation value. + +When the source or translation contains Fluent Select Expressions, then each +possible variant in the source must be matched with at least one variant in the +translation with the same HTML elements, and vice versa. + +When using Fluent in combination with the Fluent DOM package, this check will +ensure that the translation also includes any required ``data-l10n-name`` +elements that appear in the source, or any of the allowed inline elements like +``
``. + +For example, the following source: + +.. code-block:: text + + Source message with icon + +would match with: + +.. code-block:: text + + Translated message with icon + +but not: + +.. code-block:: text + + Translated message with icon + +nor + +.. code-block:: text + + Translated message
with no icon + +.. seealso:: + + * :ref:`check-fluent-source-inner-html` + * `Fluent DOM `_ + +.. AUTOGENERATED START: check-fluent-target-syntax +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-fluent-target-syntax: + +Fluent translation syntax +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 5.0 + +:Summary: Fluent syntax error in the translation. +:Scope: translated strings +:Check class: ``weblate.checks.fluent.syntax.FluentTargetSyntaxCheck`` +:Check identifier: ``fluent-target-syntax`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`fluent` +:Flag to enable: ``fluent-target-syntax`` +:Flag to ignore: ``ignore-fluent-target-syntax`` + +.. AUTOGENERATED END: check-fluent-target-syntax + +In Weblate, Fluent strings use Fluent syntax for references and variables, but +also for more complex features like defining attributes and selector variants, +including plurals. This check ensures that the syntax used in the translation +will be valid for Fluent. + +.. seealso:: + + * :ref:`check-fluent-source-syntax` + * `Fluent Syntax Guide `_ + * `Mozilla Basic Syntax Guide `_ + +.. _check-formats: + +Formatted strings +~~~~~~~~~~~~~~~~~ + +Checks that the formatting in strings is replicated between both source and translation. +Omitting format strings in translation usually causes severe problems, so the formatting in strings +should usually match the source. + +Weblate supports checking format strings in several languages. The check is not +enabled automatically, only if a string is flagged appropriately (e.g. +`c-format` for C format). Gettext adds this automatically, but you will +probably have to add it manually for other file formats or if your PO files are +not generated by :program:`xgettext`. + +Most of the format checks allow omitting format strings for plural forms having +a single count. This allows translators to write nicer strings for these cases +(`One apple` instead of `%d apple`). Turn this off by adding ``strict-format`` flag. + +The flags can be customized per string (see :ref:`additional`) or in a :ref:`component`. +Having it defined per component is simpler, but it can lead to false positives in +case the string is not interpreted as a formatting string, but format string syntax +happens to be used. + +.. hint:: + + In case specific format check is not available in Weblate, you can use + generic :ref:`check-placeholders`. + +Besides checking, this will also highlight the formatting strings to easily +insert them into translated strings: + +.. image:: /screenshots/format-highlight.webp + +.. AUTOGENERATED START: check-angularjs-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-angularjs-format: + +AngularJS interpolation string +****************************** + +:Summary: AngularJS interpolation strings do not match source. +:Scope: translated strings +:Check class: ``weblate.checks.angularjs.AngularJSInterpolationCheck`` +:Check identifier: ``angularjs_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``angularjs-format`` +:Flag to ignore: ``ignore-angularjs-format`` + +.. AUTOGENERATED END: check-angularjs-format + +:Named format string example: ``Your balance is {{amount}} {{ currency }}`` + +.. seealso:: + + * :ref:`check-formats` + * `AngularJS text interpolation `_ + +.. AUTOGENERATED START: check-automattic-components-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-automattic-components-format: + +Automattic components formatting +******************************** + +:Summary: The Automattic components' placeholders do not match the source. +:Scope: translated strings +:Check class: ``weblate.checks.format.AutomatticComponentsCheck`` +:Check identifier: ``automattic_components_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``automattic-components-format`` +:Flag to ignore: ``ignore-automattic-components-format`` + +.. AUTOGENERATED END: check-automattic-components-format + +:Simple format string example: ``They bought {{strong}}apples{{/strong}}.`` + +.. seealso:: + + * :ref:`check-formats` + * `Interpolate Components `_ + +.. AUTOGENERATED START: check-c-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-c-format: + +C format +******** + +:Summary: C format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.CFormatCheck`` +:Check identifier: ``c_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``c-format`` +:Flag to ignore: ``ignore-c-format`` + +.. AUTOGENERATED END: check-c-format + +:Simple format string example: ``There are %d apples`` +:Position format string example: ``Your balance is %1$d %2$s`` + +.. seealso:: + + * :ref:`check-formats` + * `C format strings `_ + * `C printf format `_ + + +.. AUTOGENERATED START: check-c-sharp-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-c-sharp-format: + +C# format +********* + +:Summary: C# format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.CSharpFormatCheck`` +:Check identifier: ``c_sharp_format`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`resourcedictionary` +:Flag to enable: ``c-sharp-format``, ``csharp-format`` +:Flag to ignore: ``ignore-c-sharp-format`` + +.. AUTOGENERATED END: check-c-sharp-format + +:Position format string example: ``There are {0} apples`` + +.. seealso:: + + * :ref:`check-formats` + * `C# String Format `_ + +.. AUTOGENERATED START: check-es-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-es-format: + +ECMAScript template literals +**************************** + +:Summary: ECMAScript template literals do not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.ESTemplateLiteralsCheck`` +:Check identifier: ``es_format`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`mi18n-lang` +:Flag to enable: ``es-format`` +:Flag to ignore: ``ignore-es-format`` + +.. AUTOGENERATED END: check-es-format + +:Interpolation example: ``There are ${number} apples`` + +.. seealso:: + + * :ref:`check-formats` + * `Template literals `_ + +.. AUTOGENERATED START: check-i18next-interpolation +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-i18next-interpolation: + +i18next interpolation +********************* + +.. versionadded:: 4.0 + +:Summary: The i18next interpolation does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.I18NextInterpolationCheck`` +:Check identifier: ``i18next_interpolation`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`i18next`, :ref:`i18nextv4` +:Flag to enable: ``i18next-interpolation`` +:Flag to ignore: ``ignore-i18next-interpolation`` + +.. AUTOGENERATED END: check-i18next-interpolation + +:Interpolation example: ``There are {{number}} apples`` +:Nesting example: ``There are $t(number) apples`` + +.. seealso:: + + * :ref:`check-formats` + * `i18next interpolation `_ + +.. AUTOGENERATED START: check-icu-message-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-icu-message-format: + +ICU MessageFormat +***************** + +.. versionadded:: 4.9 + +:Summary: Syntax errors and/or placeholder mismatches in ICU MessageFormat strings. +:Scope: translated strings +:Check class: ``weblate.checks.icu.ICUMessageFormatCheck`` +:Check identifier: ``icu_message_format`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`arb`, :ref:`formatjs` +:Flag to enable: ``icu-message-format`` +:Flag to ignore: ``ignore-icu-message-format`` + +.. AUTOGENERATED END: check-icu-message-format + +:Interpolation example: ``There {number, plural, one {is one apple} other {are # apples}}.`` + +This check has support for both pure ICU MessageFormat messages as well as ICU with simple +XML tags. You can configure the behavior of this check by using ``icu-flags:*``, either by +opting into XML support or by disabling certain sub-checks. For example, the following flag +enables XML support while disabling validation of plural sub-messages: + +.. code-block:: text + + icu-message-format, icu-flags:xml:-plural_selectors + ++---------------------------+------------------------------------------------------------+ +| ``xml`` | Enable support for simple XML tags. By default, XML tags | +| | are parsed loosely. Stray ``<`` characters are ignored | +| | if they are not reasonably part of a tag. | ++---------------------------+------------------------------------------------------------+ +| ``strict-xml`` | Enable support for strict XML tags. All ``<`` characters | +| | must be escaped if they are not part of a tag. | ++---------------------------+------------------------------------------------------------+ +| ``-highlight`` | Disable highlighting placeholders in the editor. | ++---------------------------+------------------------------------------------------------+ +| ``-require_other`` | Disable requiring sub-messages to have an ``other`` | +| | selector. | ++---------------------------+------------------------------------------------------------+ +| ``-submessage_selectors`` | Skip checking that sub-message selectors match the source. | ++---------------------------+------------------------------------------------------------+ +| ``-types`` | Skip checking that placeholder types match the source. | ++---------------------------+------------------------------------------------------------+ +| ``-extra`` | Skip checking that no placeholders are present that were | +| | not present in the source string. | ++---------------------------+------------------------------------------------------------+ +| ``-missing`` | Skip checking that no placeholders are missing that were | +| | present in the source string. | ++---------------------------+------------------------------------------------------------+ + +Additionally, when ``strict-xml`` is not enabled but ``xml`` is enabled, you can use the +``icu-tag-prefix:PREFIX`` flag to require that all XML tags start with a specific string. +For example, the following flag will only allow XML tags to be matched if they start with +``click here`` but not ``this``. + +.. seealso:: + + * :ref:`check-icu-message-format-syntax` + * :ref:`check-formats` + * `ICU: Formatting Messages `_ + * `Format.JS: Message Syntax `_ + +.. AUTOGENERATED START: check-java-printf-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-java-printf-format: + +Java format +*********** + +:Summary: Java format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.JavaFormatCheck`` +:Check identifier: ``java_printf_format`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`aresource`, :ref:`moko-resource`, :ref:`cmp-resource` +:Flag to enable: ``java-printf-format`` +:Flag to ignore: ``ignore-java-printf-format`` + +.. AUTOGENERATED END: check-java-printf-format + +:Simple format string example: ``There are %d apples`` +:Position format string example: ``Your balance is %1$d %2$s`` + +.. versionchanged:: 4.14 + + This used to be toggled by the ``java-format`` flag, it was changed for consistency with GNU gettext. + +.. seealso:: + + * :ref:`check-formats` + * `Java Format Strings `_ + +.. AUTOGENERATED START: check-java-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-java-format: + +Java MessageFormat +****************** + +:Summary: Java MessageFormat string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.JavaMessageFormatCheck`` +:Check identifier: ``java_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``java-format`` +:Flag to ignore: ``ignore-java-format`` + +.. AUTOGENERATED END: check-java-format + +:Flag to enable: ``auto-java-messageformat`` enables check only if there is a format string in the source +:Position format string example: ``There are {0} apples`` + +.. versionchanged:: 4.14 + + This used to be toggled by ``java-messageformat`` flag, it was changed for consistency with GNU gettext. + +This check validates that format string is valid for the Java MessageFormat +class. Besides matching format strings in the curly braces, it also verifies +single quotes as they have a special meaning. Whenever writing single quote, it +should be written as ``''``. When not paired, it is treated as beginning of +quoting and will not be shown when rendering the string. + +.. seealso:: + + * :ref:`check-formats` + * `Java MessageFormat `_ + + +.. AUTOGENERATED START: check-javascript-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-javascript-format: + +JavaScript format +***************** + +:Summary: JavaScript format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.JavaScriptFormatCheck`` +:Check identifier: ``javascript_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``javascript-format`` +:Flag to ignore: ``ignore-javascript-format`` + +.. AUTOGENERATED END: check-javascript-format + +:Simple format string example: ``There are %d apples`` + +.. seealso:: + + * :ref:`check-formats` + * `JavaScript formatting strings `_ + + +.. AUTOGENERATED START: check-laravel-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-laravel-format: + +Laravel format +************** + +:Summary: Laravel format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.LaravelFormatCheck`` +:Check identifier: ``laravel_format`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`laravel` +:Flag to enable: ``laravel-format`` +:Flag to ignore: ``ignore-laravel-format`` + +.. AUTOGENERATED END: check-laravel-format + +:Named format string example: ``The :attribute must be :value`` + +.. seealso:: + + * :ref:`check-formats` + * `Laravel translation formatting `_ + + +.. AUTOGENERATED START: check-lua-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-lua-format: + +Lua format +********** + +:Summary: Lua format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.LuaFormatCheck`` +:Check identifier: ``lua_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``lua-format`` +:Flag to ignore: ``ignore-lua-format`` + +.. AUTOGENERATED END: check-lua-format + +:Simple format string example: ``There are %d apples`` + +.. seealso:: + + * :ref:`check-formats` + * `Lua formatting strings `_ + + +.. AUTOGENERATED START: check-object-pascal-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-object-pascal-format: + +Object Pascal format +******************** + +:Summary: Object Pascal format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.ObjectPascalFormatCheck`` +:Check identifier: ``object_pascal_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``object-pascal-format`` +:Flag to ignore: ``ignore-object-pascal-format`` + +.. AUTOGENERATED END: check-object-pascal-format + +:Simple format string example: ``There are %d apples`` + +.. seealso:: + + * :ref:`check-formats` + * `Object Pascal formatting strings `_ + * `Free Pascal formatting strings `_ + * `Delphi formatting strings `_ + + +.. AUTOGENERATED START: check-percent-placeholders +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-percent-placeholders: + +Percent placeholders +******************** + +.. versionadded:: 4.0 + +:Summary: The percent placeholders do not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.PercentPlaceholdersCheck`` +:Check identifier: ``percent_placeholders`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``percent-placeholders`` +:Flag to ignore: ``ignore-percent-placeholders`` + +.. AUTOGENERATED END: check-percent-placeholders + +:Simple format string example: ``There are %number% apples`` + +.. seealso:: + + :ref:`check-formats` + + +.. AUTOGENERATED START: check-perl-brace-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-perl-brace-format: + +Perl brace format +***************** + +:Summary: Perl brace format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.PerlBraceFormatCheck`` +:Check identifier: ``perl_brace_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``perl-brace-format`` +:Flag to ignore: ``ignore-perl-brace-format`` + +.. AUTOGENERATED END: check-perl-brace-format + +:Named format string example: ``There are {number} apples`` + +.. seealso:: + + * :ref:`check-formats` + * `Perl Format Strings `_ + + +.. AUTOGENERATED START: check-perl-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-perl-format: + +Perl format +*********** + +:Summary: Perl format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.PerlFormatCheck`` +:Check identifier: ``perl_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``perl-format`` +:Flag to ignore: ``ignore-perl-format`` + +.. AUTOGENERATED END: check-perl-format + +:Simple format string example: ``There are %d apples`` +:Position format string example: ``Your balance is %1$d %2$s`` + +.. seealso:: + + * :ref:`check-formats` + * `Perl sprintf `_ + * `Perl Format Strings `_ + +.. AUTOGENERATED START: check-php-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-php-format: + +PHP format +********** + +:Summary: PHP format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.PHPFormatCheck`` +:Check identifier: ``php_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``php-format`` +:Flag to ignore: ``ignore-php-format`` + +.. AUTOGENERATED END: check-php-format + +:Simple format string example: ``There are %d apples`` +:Position format string example: ``Your balance is %1$d %2$s`` + +.. seealso:: + + * :ref:`check-formats` + * `PHP sprintf documentation `_ + * `PHP Format Strings `_ + +.. AUTOGENERATED START: check-python-brace-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-python-brace-format: + +Python brace format +******************* + +:Summary: Python brace format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.PythonBraceFormatCheck`` +:Check identifier: ``python_brace_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``python-brace-format`` +:Flag to ignore: ``ignore-python-brace-format`` + +.. AUTOGENERATED END: check-python-brace-format + +:Simple format string: ``There are {} apples`` +:Named format string example: ``Your balance is {amount} {currency}`` + +.. seealso:: + + * :ref:`check-formats` + * :ref:`Python brace format ` + * `Python Format Strings `_ + +.. AUTOGENERATED START: check-python-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-python-format: + +Python format +************* + +:Summary: Python format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.PythonFormatCheck`` +:Check identifier: ``python_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``python-format`` +:Flag to ignore: ``ignore-python-format`` + +.. AUTOGENERATED END: check-python-format + +:Simple format string: ``There are %d apples`` +:Named format string example: ``Your balance is %(amount)d %(currency)s`` + +.. seealso:: + + * :ref:`check-formats` + * :ref:`Python string formatting ` + * `Python Format Strings `_ + +.. AUTOGENERATED START: check-qt-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-qt-format: + +Qt format +********* + +:Summary: Qt format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.qt.QtFormatCheck`` +:Check identifier: ``qt_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``qt-format`` +:Flag to ignore: ``ignore-qt-format`` + +.. AUTOGENERATED END: check-qt-format + +:Position format string example: ``There are %1 apples`` + +.. seealso:: + + * :ref:`check-formats` + * `Qt QString::arg() `_ + +.. AUTOGENERATED START: check-qt-plural-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-qt-plural-format: + +Qt plural format +**************** + +:Summary: Qt plural format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.qt.QtPluralCheck`` +:Check identifier: ``qt_plural_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``qt-plural-format`` +:Flag to ignore: ``ignore-qt-plural-format`` + +.. AUTOGENERATED END: check-qt-plural-format + +:Plural format string example: ``There are %Ln apple(s)`` + +.. seealso:: + + * :ref:`check-formats` + * `Qt i18n guide `_ + +.. AUTOGENERATED START: check-ruby-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-ruby-format: + +Ruby format +*********** + +:Summary: Ruby format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.ruby.RubyFormatCheck`` +:Check identifier: ``ruby_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``ruby-format`` +:Flag to ignore: ``ignore-ruby-format`` + +.. AUTOGENERATED END: check-ruby-format + +:Simple format string example: ``There are %d apples`` +:Position format string example: ``Your balance is %1$f %2$s`` +:Named format string example: ``Your balance is %+.2f %s`` +:Named template string: ``Your balance is %{amount} %{currency}`` + +.. seealso:: + + * :ref:`check-formats` + * `Ruby Kernel#sprintf `_ + +.. AUTOGENERATED START: check-scheme-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-scheme-format: + +Scheme format +************* + +:Summary: Scheme format string does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.SchemeFormatCheck`` +:Check identifier: ``scheme_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``scheme-format`` +:Flag to ignore: ``ignore-scheme-format`` + +.. AUTOGENERATED END: check-scheme-format + +:Simple format string example: ``There are ~d apples`` + +.. seealso:: + + * :ref:`check-formats` + * `Srfi 28 `_ + * `Chicken Scheme format `_ + * `Guile Scheme formatted output `_ + +.. AUTOGENERATED START: check-vue-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-vue-format: + +Vue I18n formatting +******************* + +:Summary: The Vue I18n formatting does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.format.VueFormattingCheck`` +:Check identifier: ``vue_format`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``vue-format`` +:Flag to ignore: ``ignore-vue-format`` + +.. AUTOGENERATED END: check-vue-format + +:Named formatting: ``There are {count} apples`` +:Rails i18n formatting: ``There are %{count} apples`` +:Linked locale messages: ``@:message.dio @:message.the_world!`` + +.. seealso:: + + * :ref:`check-formats` + * `Vue I18n Formatting `_ + * `Vue I18n Linked locale messages `_ + +.. AUTOGENERATED START: check-translated +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-translated: + +Has been translated +~~~~~~~~~~~~~~~~~~~ + +:Summary: This string has been translated in the past. +:Scope: all strings +:Check class: ``weblate.checks.consistency.TranslatedCheck`` +:Check identifier: ``translated`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-translated`` + +.. AUTOGENERATED END: check-translated + +Means a string has been translated already. This can happen when the +translations have been reverted in VCS or lost otherwise. + +.. AUTOGENERATED START: check-inconsistent +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-inconsistent: + +Inconsistent +~~~~~~~~~~~~ + +:Summary: This string has more than one translation in this project or is untranslated in some components. +:Scope: all strings +:Check class: ``weblate.checks.consistency.ConsistencyCheck`` +:Check identifier: ``inconsistent`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-inconsistent`` + +.. AUTOGENERATED END: check-inconsistent + +Weblate checks translations of the same string across all translation within a +project to help you keep consistent translations. + +The check fails on differing translations of one string within a project. This +can also lead to inconsistencies in displayed checks. You can find other +translations of this string on the :guilabel:`Other occurrences` tab. + +This check applies to all components in a project that have +:ref:`component-allow_translation_propagation` turned on. + +.. hint:: + + For performance reasons, the check might not find all inconsistencies, it + limits number of matches. + +.. note:: + + This check also fires in case the string is translated in one component and + not in another. It can be used as a quick way to manually handle strings + which are untranslated in some components just by clicking on the + :guilabel:`Use this translation` button displayed on each line in the + :guilabel:`Other occurrences` tab. + + You can use :ref:`addon-weblate.autotranslate.autotranslate` add-on to + automate translating of newly added strings which are already translated in + another component. + +.. seealso:: + + :ref:`translation-consistency` + +.. AUTOGENERATED START: check-rst-references +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-rst-references: + +Inconsistent reStructuredText +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 5.10 + +:Summary: Inconsistent reStructuredText markup in the translated message. +:Scope: translated strings +:Check class: ``weblate.checks.markup.RSTReferencesCheck`` +:Check identifier: ``rst-references`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``rst-text`` +:Flag to ignore: ``ignore-rst-references`` + +.. AUTOGENERATED END: check-rst-references + +reStructuredText term references or other markup do not match source, the typical causes for these errors are: + +* Mismatched or missing backticks. +* Missing spaces or interpunction around the reference. The reStructuredText inline blocks need to be separated by non-word characters. +* Space between inline tag and backticks. +* The reference name is not being translated. +* Using quotes instead of backticks. +* Mismatched substitutions or footnote references. + +.. seealso:: + + * `reStructuredText Primer`_ + * :ref:`check-rst-syntax` + +.. AUTOGENERATED START: check-kashida +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-kashida: + +Kashida letter used +~~~~~~~~~~~~~~~~~~~ + +:Summary: The decorative kashida letters should not be used. +:Scope: translated strings +:Check class: ``weblate.checks.chars.KashidaCheck`` +:Check identifier: ``kashida`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-kashida`` + +.. AUTOGENERATED END: check-kashida + +The decorative Kashida letters should not be used in translation. These are +also known as Tatweel. + +.. seealso:: + + `Kashida on Wikipedia `_ + +.. AUTOGENERATED START: check-md-link +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-md-link: + +Markdown links +~~~~~~~~~~~~~~ + +:Summary: Markdown links do not match source. +:Scope: translated strings +:Check class: ``weblate.checks.markup.MarkdownLinkCheck`` +:Check identifier: ``md-link`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`markdown` +:Flag to enable: ``md-text`` +:Flag to ignore: ``ignore-md-link`` + +.. AUTOGENERATED END: check-md-link + +Markdown links do not match source. + +.. seealso:: + + `Markdown links `_ + +.. AUTOGENERATED START: check-md-reflink +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-md-reflink: + +Markdown references +~~~~~~~~~~~~~~~~~~~ + +:Summary: Markdown link references do not match source. +:Scope: translated strings +:Check class: ``weblate.checks.markup.MarkdownRefLinkCheck`` +:Check identifier: ``md-reflink`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`markdown` +:Flag to enable: ``md-text`` +:Flag to ignore: ``ignore-md-reflink`` + +.. AUTOGENERATED END: check-md-reflink + +Markdown link references do not match source. + +.. seealso:: + + `Markdown links `_ + +.. AUTOGENERATED START: check-md-syntax +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-md-syntax: + +Markdown syntax +~~~~~~~~~~~~~~~ + +:Summary: Markdown syntax does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.markup.MarkdownSyntaxCheck`` +:Check identifier: ``md-syntax`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`markdown` +:Flag to enable: ``md-text`` +:Flag to ignore: ``ignore-md-syntax`` + +.. AUTOGENERATED END: check-md-syntax + +Markdown syntax does not match source + +.. seealso:: + + `Markdown inlines `_ + +.. AUTOGENERATED START: check-max-length +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-max-length: + +Maximum length of translation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:Summary: Translation should not exceed given length. +:Scope: translated strings +:Check class: ``weblate.checks.chars.MaxLengthCheck`` +:Check identifier: ``max-length`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``max-length`` +:Flag to ignore: ``ignore-max-length`` + +.. AUTOGENERATED END: check-max-length + +Checks that translations are of acceptable length to fit available space. +This only checks for the length of translation characters. + +Unlike the other checks, the flag should be set as a ``key:value`` pair like +``max-length:100``. + +.. hint:: + + This check looks at number of chars, what might not be the best metric when + using proportional fonts to render the text. The :ref:`check-max-size` check + does check actual rendering of the text. + + The ``replacements:`` flag might be also useful to expand placeables before + checking the string. + + When ``xml-text`` flag is also used, the length calculation ignores XML tags. + +.. AUTOGENERATED START: check-max-size +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-max-size: + +Maximum size of translation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:Summary: Translation rendered text should not exceed given size. +:Scope: translated strings +:Check class: ``weblate.checks.render.MaxSizeCheck`` +:Check identifier: ``max-size`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``max-size`` +:Flag to ignore: ``ignore-max-size`` + +.. AUTOGENERATED END: check-max-size + +Translation rendered text should not exceed given size. It renders the text +with line wrapping and checks if it fits into given boundaries. + +This check needs one or two parameters - maximal width and maximal number of +lines. In case the number of lines is not provided, one line text is +considered. + +You can also configure used font by ``font-*`` directives (see +:ref:`custom-checks`), for example following translation flags say that the +text rendered with ubuntu font size 22 should fit into two lines and 500 +pixels: + +.. code-block:: text + + max-size:500:2, font-family:ubuntu, font-size:22 + +.. hint:: + + You might want to set ``font-*`` directives in :ref:`component` to have the same + font configured for all strings within a component. You can override those + values per string in case you need to customize it per string. + + The ``replacements:`` flag might be also useful to expand placeables before + checking the string. + + When ``xml-text`` flag is also used, the length calculation ignores XML tags. + +.. seealso:: + + * :ref:`fonts` + * :ref:`custom-checks` + * :ref:`check-max-length` + +.. AUTOGENERATED START: check-escaped-newline +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-escaped-newline: + +Mismatched \\n +~~~~~~~~~~~~~~ + +:Summary: Number of \\n literals in translation does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.chars.EscapedNewlineCountingCheck`` +:Check identifier: ``escaped_newline`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-escaped-newline`` + +.. AUTOGENERATED END: check-escaped-newline + +Usually escaped newlines are important for formatting program output. +Check fails if the number of ``\n`` literals in translation does not match the source. + +.. AUTOGENERATED START: check-end-colon +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-end-colon: + +Mismatched colon +~~~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both end with a colon. +:Scope: translated strings +:Check class: ``weblate.checks.chars.EndColonCheck`` +:Check identifier: ``end_colon`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-end-colon`` + +.. AUTOGENERATED END: check-end-colon + +Checks that colons are replicated between both source and translation. The +presence of colons is also checked for various languages where they do not +belong (Chinese or Japanese). + +.. seealso:: + + `Colon on Wikipedia `_ + +.. AUTOGENERATED START: check-end-ellipsis +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-end-ellipsis: + +Mismatched ellipsis +~~~~~~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both end with an ellipsis. +:Scope: translated strings +:Check class: ``weblate.checks.chars.EndEllipsisCheck`` +:Check identifier: ``end_ellipsis`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-end-ellipsis`` + +.. AUTOGENERATED END: check-end-ellipsis + +Checks that trailing ellipses are replicated between both source and translation. +This only checks for real ellipsis (``…``) not for three dots (``...``). + +An ellipsis is usually rendered nicer than three dots in print, and sounds better with text-to-speech. + +.. seealso:: + + `Ellipsis on Wikipedia `_ + + +.. AUTOGENERATED START: check-end-exclamation +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-end-exclamation: + +Mismatched exclamation mark +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both end with an exclamation mark. +:Scope: translated strings +:Check class: ``weblate.checks.chars.EndExclamationCheck`` +:Check identifier: ``end_exclamation`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-end-exclamation`` + +.. AUTOGENERATED END: check-end-exclamation + +Checks that exclamations are replicated between both source and translation. +The presence of exclamation marks is also checked for various languages where +they do not belong (Chinese, Japanese, Korean, Armenian, Limbu, Myanmar or +Nko). + +.. seealso:: + + `Exclamation mark on Wikipedia `_ + +.. AUTOGENERATED START: check-end-stop +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-end-stop: + +Mismatched full stop +~~~~~~~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both end with a full stop. +:Scope: translated strings +:Check class: ``weblate.checks.chars.EndStopCheck`` +:Check identifier: ``end_stop`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-end-stop`` + +.. AUTOGENERATED END: check-end-stop + +Checks that full stops are replicated between both source and translation. +The presence of full stops is checked for various languages where they do not belong +(Chinese, Japanese, Devanagari or Urdu). + +.. seealso:: + + `Full stop on Wikipedia `_ + +.. AUTOGENERATED START: check-end-interrobang +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-end-interrobang: + +Mismatched interrobang +~~~~~~~~~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both end with an interrobang expression. +:Scope: translated strings +:Check class: ``weblate.checks.chars.EndInterrobangCheck`` +:Check identifier: ``end_interrobang`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-end-interrobang`` + +.. AUTOGENERATED END: check-end-interrobang + +Checks that interrobang marks are replicated between both source and translation. +It allows the swap between "!?" and "?!". + +.. seealso:: + + `Interrobang mark on Wikipedia `_ + +.. AUTOGENERATED START: check-end-question +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-end-question: + +Mismatched question mark +~~~~~~~~~~~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both end with a question mark. +:Scope: translated strings +:Check class: ``weblate.checks.chars.EndQuestionCheck`` +:Check identifier: ``end_question`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-end-question`` + +.. AUTOGENERATED END: check-end-question + +Checks that question marks are replicated between both source and translation. +The presence of question marks is also checked for various languages where they +do not belong (Armenian, Arabic, Chinese, Korean, Japanese, Ethiopic, Vai or +Coptic). + +.. seealso:: + + `Question mark on Wikipedia `_ + + +.. AUTOGENERATED START: check-end-semicolon +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-end-semicolon: + +Mismatched semicolon +~~~~~~~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both end with a semicolon. +:Scope: translated strings +:Check class: ``weblate.checks.chars.EndSemicolonCheck`` +:Check identifier: ``end_semicolon`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-end-semicolon`` + +.. AUTOGENERATED END: check-end-semicolon + +Checks that semicolons at the end of sentences are replicated between both source and translation. + +.. seealso:: + + `Semicolon on Wikipedia `_ + +.. AUTOGENERATED START: check-newline-count +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-newline-count: + +Mismatching line breaks +~~~~~~~~~~~~~~~~~~~~~~~ + +:Summary: Number of new lines in translation does not match source. +:Scope: translated strings +:Check class: ``weblate.checks.chars.NewLineCountCheck`` +:Check identifier: ``newline-count`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-newline-count`` + +.. AUTOGENERATED END: check-newline-count + +Usually newlines are important for formatting program output. +Check fails if the number of new lines in translation does not match the source. + + +.. AUTOGENERATED START: check-plurals +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-plurals: + +Missing plurals +~~~~~~~~~~~~~~~ + +:Summary: Some plural forms are untranslated. +:Scope: translated strings +:Check class: ``weblate.checks.consistency.PluralsCheck`` +:Check identifier: ``plurals`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-plurals`` + +.. AUTOGENERATED END: check-plurals + +Checks that all plural forms of a source string have been translated. +Specifics on how each plural form is used can be found in the string definition. + +Failing to fill in plural forms will in some cases lead to displaying nothing when +the plural form is in use. + +.. AUTOGENERATED START: check-multiple-capital +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-multiple-capital: + +Multiple capitals +~~~~~~~~~~~~~~~~~ + +.. versionadded:: 5.16 + +:Summary: Translation contains words with multiple misplaced capital letters. +:Scope: translated strings +:Check class: ``weblate.checks.chars.MultipleCapitalCheck`` +:Check identifier: ``multiple_capital`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-multiple-capital`` + +.. AUTOGENERATED END: check-multiple-capital + +Checks for misplaced capitalization by detecting words that contain consecutive +uppercase letters in otherwise lowercase or normally capitalized text (for +example, ``HEllo`` or ``CAmelCase``). Strings that contain capitalization in the +source string are allowed to contain capitalization in the translation. + +.. AUTOGENERATED START: check-kabyle-characters +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-kabyle-characters: + +Non‑standard characters in Kabyle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 5.12 + +:Summary: Use standardized Latin Kabyle characters (e.g. ɣ instead of Greek γ; ɛ instead of ε). +:Scope: translated strings +:Check class: ``weblate.checks.chars.KabyleCharactersCheck`` +:Check identifier: ``kabyle-characters`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-kabyle-characters`` + +.. AUTOGENERATED END: check-kabyle-characters + +Checks that Kabyle translations use correct Kabyle letters and not similar +Greek ones, which were often used before Kabyle characters were standardized in +Unicode. + + +.. AUTOGENERATED START: check-placeholders +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-placeholders: + +Placeholders +~~~~~~~~~~~~ + +.. versionchanged:: 4.3 + + You can use regular expression as placeholder. + +.. versionchanged:: 4.13 + + With the ``case-insensitive`` flag, the placeholders are not case-sensitive. + +:Summary: Translation is missing some placeholders. +:Scope: translated strings +:Check class: ``weblate.checks.placeholders.PlaceholderCheck`` +:Check identifier: ``placeholders`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``placeholders`` +:Flag to ignore: ``ignore-placeholders`` + +.. AUTOGENERATED END: check-placeholders + +Translation is missing some placeholders. These are either extracted from the +translation file or defined manually using ``placeholders`` flag, more can be +separated with colon, strings with space can be quoted: + +.. code-block:: text + + placeholders:$URL$:$TARGET$:"some long text" + +In case you have some syntax for placeholders, you can use a regular expression: + +.. code-block:: text + + placeholders:r"%[^% ]%" + +You can also have case insensitive placeholders: + +.. code-block:: text + + placeholders:$URL$:$TARGET$,case-insensitive + +.. seealso:: + + :ref:`custom-checks` + +.. AUTOGENERATED START: check-prohibited-initial-character +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-prohibited-initial-character: + +Prohibited initial character +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 5.9 + +:Summary: The string starts with a prohibited character in CSV. +:Scope: glossary strings +:Check class: ``weblate.checks.glossary.ProhibitedInitialCharacterCheck`` +:Check identifier: ``prohibited_initial_character`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-prohibited-initial-character`` + +.. AUTOGENERATED END: check-prohibited-initial-character + +The glossary is often shared as CSV and using some characters at the beginning is +restricted by many applications as these can cause the text being evaluated as +an expression. This also affects :ref:`glossary-mt` where many services use CSV +for synchronizing glossaries and reject such strings. + +.. AUTOGENERATED START: check-punctuation-spacing +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-punctuation-spacing: + +Punctuation spacing +~~~~~~~~~~~~~~~~~~~ + +.. versionchanged:: 5.10 + + This check used to apply to Breton language as well, but it was limited to French only. + +:Summary: Missing non breakable space before double punctuation sign. +:Scope: translated strings +:Check class: ``weblate.checks.chars.PunctuationSpacingCheck`` +:Check identifier: ``punctuation_spacing`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-punctuation-spacing`` + +.. AUTOGENERATED END: check-punctuation-spacing + +Checks that there is non breakable space before double punctuation sign +(exclamation mark, question mark, semicolon and colon). This rule is used only +in a few selected languages like French, where space before double +punctuation sign is a typographic rule. + +.. seealso:: + + `French and English spacing on Wikipedia `_ + +.. AUTOGENERATED START: check-regex +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-regex: + +Regular expression +~~~~~~~~~~~~~~~~~~ + +.. versionchanged:: 5.10 + + Extended support for advanced regular expressions including Unicode codepoint properties. + +:Summary: Translation does not match regular expression. +:Scope: translated strings +:Check class: ``weblate.checks.placeholders.RegexCheck`` +:Check identifier: ``regex`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``regex`` +:Flag to ignore: ``ignore-regex`` + +.. AUTOGENERATED END: check-regex + +Translation does not match regular expression. The expression is either extracted from the +translation file or defined manually using ``regex`` flag: + +.. code-block:: text + + regex:^foo|bar$ + +The matching also supports Unicode codepoint properties, including scripts and blocks: + +.. code-block:: text + + regex:^[-_\p{L}\p{N}\p{sc=Deva}\p{sc=Thai}]{1,32}$ + +.. hint:: + + Use :ref:`check-placeholders` for detecting missing placeholders in the string. + +.. seealso:: + + `regex documentation `_ + +.. AUTOGENERATED START: check-rst-syntax +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-rst-syntax: + +reStructuredText syntax error +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 5.10 + +:Summary: reStructuredText syntax error in the translation. +:Scope: translated strings +:Check class: ``weblate.checks.markup.RSTSyntaxCheck`` +:Check identifier: ``rst-syntax`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``rst-text`` +:Flag to ignore: ``ignore-rst-syntax`` + +.. AUTOGENERATED END: check-rst-syntax + +reStructuredText syntax error in the translation. Issues to look for: + +* Mismatched closing/opening tags. +* Missing spaces or interpunction around the reference. The reStructuredText inline blocks need to be separated by non-word characters. +* Using quotes instead of backticks. + +.. seealso:: + + * `reStructuredText Primer`_ + * :ref:`check-rst-references` + +.. AUTOGENERATED START: check-reused +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-reused: + +Reused translation +~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.18 + +:Summary: Different strings are translated the same. +:Scope: translated strings +:Check class: ``weblate.checks.consistency.ReusedCheck`` +:Check identifier: ``reused`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-reused`` + +.. AUTOGENERATED END: check-reused + +Check that fails if the same translation is used on different source strings. +Such translations can be intentional, but can also confuse users. + + +.. AUTOGENERATED START: check-same-plurals +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-same-plurals: + +Same plurals +~~~~~~~~~~~~ + +:Summary: Some plural forms are translated in the same way. +:Scope: translated strings +:Check class: ``weblate.checks.consistency.SamePluralsCheck`` +:Check identifier: ``same-plurals`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-same-plurals`` + +.. AUTOGENERATED END: check-same-plurals + +Check that fails if some plural forms are duplicated in the translation. +In most languages they have to be different. + +.. AUTOGENERATED START: check-begin-newline +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-begin-newline: + +Starting newline +~~~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both start with a newline. +:Scope: translated strings +:Check class: ``weblate.checks.chars.BeginNewlineCheck`` +:Check identifier: ``begin_newline`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-begin-newline`` + +.. AUTOGENERATED END: check-begin-newline + +Newlines usually appear in source strings for good reason, omissions or additions +can lead to formatting problems when the translated text is put to use. + +.. seealso:: + + :ref:`check-end-newline` + +.. AUTOGENERATED START: check-begin-space +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-begin-space: + +Starting spaces +~~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both start with same number of spaces. +:Scope: translated strings +:Check class: ``weblate.checks.chars.BeginSpaceCheck`` +:Check identifier: ``begin_space`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-begin-space`` + +.. AUTOGENERATED END: check-begin-space + +A space in the beginning of a string is usually used for indentation in the interface and thus +important to keep. + +.. AUTOGENERATED START: check-end-newline +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-end-newline: + +Trailing newline +~~~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both end with a newline. +:Scope: translated strings +:Check class: ``weblate.checks.chars.EndNewlineCheck`` +:Check identifier: ``end_newline`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-end-newline`` + +.. AUTOGENERATED END: check-end-newline + +Newlines usually appear in source strings for good reason, omissions or additions +can lead to formatting problems when the translated text is put to use. + +.. seealso:: + + :ref:`check-begin-newline` + +.. AUTOGENERATED START: check-end-space +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-end-space: + +Trailing space +~~~~~~~~~~~~~~ + +:Summary: Source and translation do not both end with a space. +:Scope: translated strings +:Check class: ``weblate.checks.chars.EndSpaceCheck`` +:Check identifier: ``end_space`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-end-space`` + +.. AUTOGENERATED END: check-end-space + +Checks that trailing spaces are replicated between both source and translation. + +Trailing space is usually utilized to space out neighbouring elements, so +removing it might break layout. + + +.. AUTOGENERATED START: check-same +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-same: + +Unchanged translation +~~~~~~~~~~~~~~~~~~~~~ + +:Summary: Source and translation are identical. +:Scope: translated strings +:Check class: ``weblate.checks.same.SameCheck`` +:Check identifier: ``same`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-same`` + +.. AUTOGENERATED END: check-same + +Happens if the source and corresponding translation strings are identical, down +to at least one of the plural forms. Some strings commonly found across all +languages are ignored, and various markups are stripped. This reduces the +number of false positives. + +This check can help find strings mistakenly untranslated. + +The default behavior of this check is to exclude words from the built-in terms +list from the checking. These are words which are frequently not being +translated. This is useful to avoid false positives on short strings, which +consist only of a single word which is the same in several languages. This list +can be disabled by adding ``strict-same`` flag to a string or component. + +.. versionchanged:: 4.17 + + With ``check-glossary`` flag (see :ref:`check-check-glossary`), the + untranslatable glossary terms are excluded from the checking. + +.. seealso:: + + * :ref:`check-check-glossary` + * :ref:`component` + * :ref:`custom-checks` + +.. AUTOGENERATED START: check-safe-html +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-safe-html: + +Unsafe HTML +~~~~~~~~~~~ + +:Summary: The translation uses unsafe HTML markup. +:Scope: translated strings +:Check class: ``weblate.checks.markup.SafeHTMLCheck`` +:Check identifier: ``safe-html`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`html`, :ref:`markdown`, :ref:`asciidoc` +:Flag to enable: ``safe-html`` +:Flag to ignore: ``ignore-safe-html`` + +.. AUTOGENERATED END: check-safe-html + +The translation uses unsafe HTML markup. This check has to be enabled using +``safe-html`` flag (see :ref:`custom-checks`). There is also accompanied +autofixer which can automatically sanitize the markup. + +.. hint:: + + When ``md-text`` flag is also used, the Markdown style links are also allowed. + +.. seealso:: + + The HTML check is performed by the `Ammonia `_ + library. + +.. AUTOGENERATED START: check-url +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-url: + +URL +~~~ + +:Summary: The translation does not contain an URL. +:Scope: translated strings +:Check class: ``weblate.checks.markup.URLCheck`` +:Check identifier: ``url`` +:Trigger: This check needs to be enabled using a flag. +:Flag to enable: ``url`` +:Flag to ignore: ``ignore-url`` + +.. AUTOGENERATED END: check-url + +The translation does not contain an URL. This is triggered only in case the +unit is marked as containing URL. In that case the translation has to be a +valid URL. + +.. AUTOGENERATED START: check-xml-tags +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-xml-tags: + +XML markup +~~~~~~~~~~ + +:Summary: XML tags in translation do not match source. +:Scope: translated strings +:Check class: ``weblate.checks.markup.XMLTagsCheck`` +:Check identifier: ``xml-tags`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-xml-tags`` + +.. AUTOGENERATED END: check-xml-tags + +This usually means the resulting output will look different. In most cases this is +not a desired result from changing the translation, but occasionally it is. + +Checks that XML tags are replicated between both source and translation. + +The check is automatically enabled for XML like strings. You might need to add +``xml-text`` flag in some cases to force turning it on. + +.. note:: + + This check is disabled by the ``safe-html`` flag as the HTML cleanup done by + it can produce HTML markup which is not valid XML. + + +.. AUTOGENERATED START: check-xml-invalid +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-xml-invalid: + +XML syntax +~~~~~~~~~~ + +:Summary: The translation is not valid XML. +:Scope: translated strings +:Check class: ``weblate.checks.markup.XMLValidityCheck`` +:Check identifier: ``xml-invalid`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-xml-invalid`` + +.. AUTOGENERATED END: check-xml-invalid + +The XML markup is not valid. + +The check is automatically enabled for XML like strings. You might need to add +``xml-text`` flag in some cases to force turning it on. + +.. note:: + + This check is disabled by the ``safe-html`` flag as the HTML cleanup done by + it can produce HTML markup which is not valid XML. + +.. AUTOGENERATED START: check-zero-width-space +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-zero-width-space: + +Zero-width space +~~~~~~~~~~~~~~~~ + +:Summary: Translation contains extra zero-width space character. +:Scope: translated strings +:Check class: ``weblate.checks.chars.ZeroWidthSpaceCheck`` +:Check identifier: ``zero-width-space`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-zero-width-space`` + +.. AUTOGENERATED END: check-zero-width-space + +Zero-width space () characters are used to break messages within words (word wrapping). + +As they are usually inserted by mistake, this check is triggered once they are present +in translation. Some programs might have problems when this character is used. + +.. seealso:: + + `Zero width space on Wikipedia `_ + + +Source checks +------------- + +Source checks can help developers improve the quality of source strings. + +.. AUTOGENERATED START: check-ellipsis +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-ellipsis: + +Ellipsis +~~~~~~~~ + +:Summary: The string uses three dots ``(...)`` instead of an ellipsis character ``(…)``. +:Scope: source strings +:Check class: ``weblate.checks.source.EllipsisCheck`` +:Check identifier: ``ellipsis`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-ellipsis`` + +.. AUTOGENERATED END: check-ellipsis + +This fails when the string uses three dots (``...``) when it should use an ellipsis character (``…``). + +Using the Unicode character is in most cases the better approach and looks better +rendered, and may sound better with text-to-speech. + +.. seealso:: + + `Ellipsis on Wikipedia `_ + +.. AUTOGENERATED START: check-fluent-source-inner-html +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-fluent-source-inner-html: + +Fluent source inner HTML +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 5.0 + +:Summary: Fluent source should be valid inner HTML. +:Scope: source strings +:Check class: ``weblate.checks.fluent.inner_html.FluentSourceInnerHTMLCheck`` +:Check identifier: ``fluent-source-inner-html`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`fluent` +:Flag to enable: ``fluent-source-inner-html`` +:Flag to ignore: ``ignore-fluent-source-inner-html`` + +.. AUTOGENERATED END: check-fluent-source-inner-html + +Fluent is often used in contexts where the value for a Message (or Term) is +meant to be used directly as ``.innerHTML`` (rather than ``.textContent``) for +some HTML element. For example, when using the Fluent DOM package. + +The aim of this check is to predict how the value will be parsed as inner HTML, +assuming a HTML5 conforming parser, to catch cases where there would be some +"unintended" loss of the string, without being too strict about technical +parsing errors that do *not* lead to a loss of the string. + +This check is applied to the value of Fluent Messages or Terms, but not their +Attributes. For Messages, the Fluent Attributes are often just HTML attribute +values, so can be arbitrary strings. For Terms, the Fluent Attributes are +often language properties that can only be referenced in the selectors of Fluent +Select Expressions. + +Generally, most Fluent values are not expected to contain any HTML markup. +Therefore, this check does not expect or want translators and developers to have +to care about strictly avoiding *any* technical HTML5 parsing errors (let alone +XHTML parsing errors). Instead, this check will just want to warn them when they +may have unintentionally opened a HTML tag or inserted a character reference. + +Moreover, for the Fluent values that intentionally contain HTML tags or +character references, this check will verify some "good practices", such as +matching closing and ending tags, valid character references, and quoted +attribute values. In addition, whilst the HTML5 specification technically allows +for quite arbitrary tag and attribute names, this check will restrain them to +some basic ASCII values that should cover the standard HTML5 element tags and +attributes, as well as allow *some* custom element or attribute names. This is +partially to ensure that the user is using HTML intentionally. + +Examples: + +.. list-table:: Fluent inner HTML examples + :header-rows: 1 + + * - Value + - Warns? + - Reason + + * - ``three`` + - yes + - Missing a closing tag. + + * - ``three `` + - yes + - ``four`` is not a HTML void element, so should not self-close. + + * - ``text`` + - no + - Custom element tag with a matching closing tag. + + * - ``a b`` + - no + - ``img`` is a HTML void element. Self-closing is allowed. + + * - ``a
b`` + - no + - ``br`` is a HTML void element. + + * - ```` + - yes + - The attribute value is not quoted. + + * - ```` + - yes + - Non-ASCII tag name. + + * - ``kindðical`` + - yes + - The ``ð`` part would be converted to ``ð``. + + * - ``kindðical`` + - no + - The character reference seems to be intentional. + + * - ``three<e;four`` + - yes + - The ``<e;`` part would be converted to ```_ + +.. AUTOGENERATED START: check-fluent-source-syntax +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-fluent-source-syntax: + +Fluent source syntax +~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 5.0 + +:Summary: Fluent syntax error in the source. +:Scope: source strings +:Check class: ``weblate.checks.fluent.syntax.FluentSourceSyntaxCheck`` +:Check identifier: ``fluent-source-syntax`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`fluent` +:Flag to enable: ``fluent-source-syntax`` +:Flag to ignore: ``ignore-fluent-source-syntax`` + +.. AUTOGENERATED END: check-fluent-source-syntax + +In Weblate, Fluent strings use Fluent syntax for references and variables, but +also for more complex features like defining attributes and selector variants, +including plurals. This check ensures that the syntax used in source will be +valid for Fluent. + +.. seealso:: + + * :ref:`check-fluent-target-syntax` + * `Fluent Syntax Guide `_ + * `Mozilla Basic Syntax Guide `_ + +.. AUTOGENERATED START: check-icu-message-format-syntax +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-icu-message-format-syntax: + +ICU MessageFormat syntax +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.9 + +:Summary: Syntax errors in ICU MessageFormat strings. +:Scope: source strings +:Check class: ``weblate.checks.icu.ICUSourceCheck`` +:Check identifier: ``icu_message_format_syntax`` +:Trigger: This check needs to be enabled using a flag. +:File formats automatically enabling this check: :ref:`arb`, :ref:`formatjs` +:Flag to enable: ``icu-message-format`` +:Flag to ignore: ``ignore-icu-message-format`` + +.. AUTOGENERATED END: check-icu-message-format-syntax + +.. seealso:: + + :ref:`check-icu-message-format` + +.. AUTOGENERATED START: check-long-untranslated +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-long-untranslated: + +Long untranslated +~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.1 + +:Summary: The string has not been translated for a long time. +:Scope: source strings +:Check class: ``weblate.checks.source.LongUntranslatedCheck`` +:Check identifier: ``long_untranslated`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-long-untranslated`` + +.. AUTOGENERATED END: check-long-untranslated + +When the string has not been translated for a long time, it can indicate a problem in a +source string making it hard to translate. + +.. AUTOGENERATED START: check-multiple-failures +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-multiple-failures: + +Multiple failing checks +~~~~~~~~~~~~~~~~~~~~~~~ + +:Summary: The translations in several languages have failing checks. +:Scope: source strings +:Check class: ``weblate.checks.source.MultipleFailingCheck`` +:Check identifier: ``multiple_failures`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-multiple-failures`` + +.. AUTOGENERATED END: check-multiple-failures + +Numerous translations of this string have failing quality checks. This is +usually an indication that something could be done to improve the source +string. + +This check failing can quite often be caused by a missing full stop at the end of +a sentence, or similar minor issues which translators tend to fix in +translation, while it would be better to fix it in the source string. + +.. AUTOGENERATED START: check-unnamed-format +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-unnamed-format: + +Multiple unnamed variables +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.1 + +:Summary: There are multiple unnamed variables in the string, making it impossible for translators to reorder them. +:Scope: source strings +:Check class: ``weblate.checks.format.MultipleUnnamedFormatsCheck`` +:Check identifier: ``unnamed_format`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-unnamed-format`` + +.. AUTOGENERATED END: check-unnamed-format + +There are multiple unnamed variables in the string, making it impossible for +translators to reorder them. + +Consider using named variables instead to allow translators to reorder them. + +.. AUTOGENERATED START: check-optional-plural +.. This section is automatically generated by `./manage.py list_checks`. Do not edit manually. + +.. _check-optional-plural: + +Unpluralised +~~~~~~~~~~~~ + +:Summary: The string is used as plural, but not using plural forms. +:Scope: source strings +:Check class: ``weblate.checks.source.OptionalPluralCheck`` +:Check identifier: ``optional_plural`` +:Trigger: This check is always enabled but can be ignored using a flag. +:Flag to ignore: ``ignore-optional-plural`` + +.. AUTOGENERATED END: check-optional-plural + +The string is used as a plural, but does not use plural forms. In case your +translation system supports this, you should use the plural aware variant of +it. + +For example with Gettext in Python it could be: + +.. code-block:: python + + from gettext import ngettext + + print(ngettext("Selected %d file", "Selected %d files", files) % files) + + +.. _placeables-mt: + +Placeables in automatic suggestion +---------------------------------- + +Checks for placeables expose information on current placeables and this can be +used to instruct automatic suggestion engines to keep them. The support for +this varies in different services and in many cases there is no way to enforce +keeping placeables intact. + +.. seealso:: + + :doc:`/admin/machine` + +.. _reStructuredText Primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html diff --git a/docs/snippets/machines-autogenerated.rst b/docs/snippets/machines-autogenerated.rst new file mode 100644 index 000000000000..94dacb5862ca --- /dev/null +++ b/docs/snippets/machines-autogenerated.rst @@ -0,0 +1,1184 @@ +.. AUTOGENERATED START: alibaba +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-alibaba: + +Alibaba +------- + +.. versionadded:: 5.3 + +:Service ID: ``alibaba`` +:Maximal score: 80 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | Access key ID | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``secret`` | Access key secret | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``region`` | Region ID | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: alibaba + +Alibaba Translate is a neural machine translation service for translating text +and it supports up to 214 language pairs. + +.. seealso:: + + `Alibaba Translate Documentation `_ + +.. AUTOGENERATED START: anthropic +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-anthropic: + +Anthropic +--------- + +.. versionadded:: 5.16 + +:Service ID: ``anthropic`` +:Maximal score: 90 +:Advanced features: * :ref:`glossary-mt` +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``base_url`` | Anthropic API URL | Base URL of the Anthropic API. Leave empty to use the default URL. | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``model`` | Anthropic model | Available choices: | + | | | | + | | | ``claude-sonnet-4-5`` -- Claude Sonnet 4.5 (Recommended) | + | | | | + | | | ``claude-haiku-4-5`` -- Claude Haiku 4.5 | + | | | | + | | | ``claude-opus-4-5`` -- Claude Opus 4.5 | + | | | | + | | | ``custom`` -- Custom model | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``persona`` | Translator persona | Describe the persona of translator to improve the accuracy of the translation. For example: “You are a squirrel breeder.” | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``style`` | Translator style | Describe the style of translation. For example: “Use informal language.” | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``custom_model`` | Custom model name | Only needed when model is set to 'Custom model' | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``max_tokens`` | Max tokens | Maximum number of tokens to generate in the response. | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + + +.. AUTOGENERATED END: anthropic + +Performs translation using `Anthropic's Claude`_ models. + +The Anthropic API provides access to the Claude family of models, which are +known for their strong reasoning and language capabilities. You need an API key +from Anthropic to use this service. + +Use persona and style fields to further fine-tune translations. These will be +used in a prompt for Claude and allow you to change the style of the +translations. + +The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. + +.. seealso:: + + * `Anthropic API documentation `_ + * `Anthropic Console `_ + +.. _Anthropic's Claude: https://www.anthropic.com/ + +.. AUTOGENERATED START: apertium-apy +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-apertium-apy: + +Apertium APy +------------ + +:Service ID: ``apertium-apy`` +:Maximal score: 88 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``url`` | API URL | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: apertium-apy + +A libre software machine translation platform providing translations to +a limited set of languages. + +The recommended way to use Apertium is to run your own Apertium-APy server. + +.. seealso:: + + * `Apertium website `_ + * `Apertium APy documentation `_ + + + +.. AUTOGENERATED START: aws +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-aws: + +Amazon Translate +---------------- + +:Service ID: ``aws`` +:Maximal score: 88 +:Advanced features: * :ref:`glossary-mt` +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | Access key ID | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``secret`` | API secret key | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``region`` | Region name | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: aws + +Amazon Translate is a neural machine translation service for translating text +to and from English across a breadth of supported languages. +The service requires the `TranslateFullAccess` Managed Policy. + +The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. + +.. seealso:: + + * `Amazon Translate Documentation `_ + * `AWS TranslateFullAccess Policy `_ + + +.. AUTOGENERATED START: azure-openai +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-azure-openai: + +Azure OpenAI +------------ + +.. versionadded:: 5.8 + +:Service ID: ``azure-openai`` +:Maximal score: 90 +:Advanced features: * :ref:`glossary-mt` +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``base_url`` | API URL | | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``model`` | LLM model | | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``persona`` | Translator persona | Describe the persona of translator to improve the accuracy of the translation. For example: “You are a squirrel breeder.” | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``style`` | Translator style | Describe the style of translation. For example: “Use informal language.” | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``azure_endpoint`` | Azure OpenAI endpoint URL | Endpoint URL of the instance, e.g: https://my-instance.openai.azure.com. | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``deployment`` | Azure OpenAI deployment | The model's unique deployment name. | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + + +.. AUTOGENERATED END: azure-openai + +Performs translation using `OpenAI`_ hosted on Azure. + +.. seealso:: + + :ref:`mt-openai` + +.. AUTOGENERATED START: baidu +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-baidu: + +Baidu +----- + +:Service ID: ``baidu`` +:Maximal score: 90 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | Client ID | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``secret`` | Client secret | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: baidu + +Machine translation service provided by Baidu. + +This service uses an API and you need to obtain an ID and API key from Baidu to use it. + +.. seealso:: + + `Baidu Translate API `_ + +.. AUTOGENERATED START: cyrtranslit +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-cyrtranslit: + +CyrTranslit +----------- + +.. versionadded:: 5.7 + +:Service ID: ``cyrtranslit`` +:Maximal score: 100 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: cyrtranslit + + +Machine translation service using the Cyrtranslit library. + +This service converts text between Cyrillic and Latin scripts for languages that have both scripts. + +.. seealso:: + + `Cyrtranslit repository `_ + + +.. AUTOGENERATED START: deepl +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-deepl: + +DeepL +----- + +:Service ID: ``deepl`` +:Maximal score: 91 +:Advanced features: * :ref:`placeables-mt` + * :ref:`glossary-mt` +:Configuration: +---------------------+---------------------------+-------------------------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+-------------------------------------------------------------------------------------+ + | ``url`` | API URL | | + +---------------------+---------------------------+-------------------------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+-------------------------------------------------------------------------------------+ + | ``formality`` | Formality | Uses the specified formality if language is not specified as (in)formal | + +---------------------+---------------------------+-------------------------------------------------------------------------------------+ + | ``context`` | Translation context | Describe the context of the translation to improve the accuracy of the translation. | + +---------------------+---------------------------+-------------------------------------------------------------------------------------+ + | ``next_gen`` | Use next-gen model | Prefer next-gen LLM over classic machine translation model. | + +---------------------+---------------------------+-------------------------------------------------------------------------------------+ + + +.. AUTOGENERATED END: deepl + +DeepL is paid service providing good machine translation for a few languages. +You need to purchase :guilabel:`DeepL API` subscription or you can use legacy +:guilabel:`DeepL Pro (classic)` plan. + +API URL to use with the DeepL service. At the time of writing, there is the v1 API +as well as a free and a paid version of the v2 API. + +``https://api.deepl.com/v2/`` (default in Weblate) + Is meant for API usage on the paid plan, and the subscription is usage-based. +``https://api-free.deepl.com/v2/`` + Is meant for API usage on the free plan, and the subscription is usage-based. +``https://api.deepl.com/v1/`` + Is meant for CAT tools and is usable with a per-user subscription. + +.. note:: + + Previously Weblate was classified as a CAT tool by DeepL, so it was supposed + to use the v1 API, but now is supposed to use the v2 API. Therefore it + defaults to v2, and you can change it to v1 in case you have an existing CAT + subscription and want Weblate to use that. + +Weblate supports DeepL formality, it will choose matching one based on the +language (for example, there is ``de@formal`` and ``de@informal``). + +The translation context can optionally be specified to improve translations quality. Read more on that in +`DeepL translation context documentation `_. + +The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. + +.. seealso:: + + * `DeepL translator `_ + * `DeepL pricing `_ + * `DeepL API documentation `_ + +.. AUTOGENERATED START: glosbe +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-glosbe: + +Glosbe +------ + +:Service ID: ``glosbe`` +:Maximal score: 90 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: glosbe + +Free dictionary and translation memory for almost every living language. + +The API is gratis to use, but usage of the translations is subject to the +license of the used data source. There is a limit of calls that may be done +from one IP in a set period of time, to prevent abuse. + +.. seealso:: + + `Glosbe website `_ + + +.. AUTOGENERATED START: google-translate +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-google-translate: + +Google Cloud Translation Basic +------------------------------ + +:Service ID: ``google-translate`` +:Maximal score: 90 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: google-translate + +Machine translation service provided by the Google Cloud services. + +This service uses the Google Translation API v2, and you need to obtain an API key and turn on +billing in the Google API console. + +.. seealso:: + + `Google translate documentation `_ + +.. AUTOGENERATED START: google-translate-api-v3 +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-google-translate-api-v3: + +Google Cloud Translation Advanced +--------------------------------- + +:Service ID: ``google-translate-api-v3`` +:Maximal score: 90 +:Advanced features: * :ref:`placeables-mt` + * :ref:`glossary-mt` +:Configuration: +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ + | ``credentials`` | Google Translate service account info | Enter a JSON key for the service account. | + +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ + | ``project`` | Google Translate project | Enter the numeric or alphanumeric ID of your Google Cloud project. | + +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ + | ``location`` | Google Translate location | Choose a Google Cloud Translation region that is used for the Google Cloud project or is closest to you. | + +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ + | ``bucket_name`` | Google Storage Bucket name | Enter the name of the Google Cloud Storage bucket that is used to store the Glossary files. | + +---------------------+---------------------------------------+----------------------------------------------------------------------------------------------------------+ + + +.. AUTOGENERATED END: google-translate-api-v3 + +Machine translation service provided by the Google Cloud services. + +This service uses the Google Translation API v3 and you need credentials in JSON format to access it. + +In order to use this service, you first need to go through the following steps: + +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Cloud Translation.`_ +4. `Setup Authentication.`_ + +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://docs.cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the Cloud Translation.: https://docs.cloud.google.com/translate/docs +.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html + + +Optionally, you can configure the service to use :ref:`glossary` by setting up a Bucket: + +1. `Create a Google Cloud bucket.`_ +2. `Set bucket location to "us-central1".`_ +3. `Grant 'Storage Admin' permission to the Service Account.`_ + +.. _Create a Google Cloud bucket.: https://docs.cloud.google.com/storage/docs/creating-buckets +.. _Set bucket location to "us-central1".: https://docs.cloud.google.com/translate/docs/migrate-to-v3#resources_projects_and_locations +.. _Grant 'Storage Admin' permission to the Service Account.: https://docs.cloud.google.com/translate/docs/access-control + + +.. seealso:: + + * `Google translate documentation `_ + * `Authenticate to Cloud services using client libraries `_ + * `Creating Google Translate project `_ + * `Google Cloud App Engine locations `_ + +.. _mt-ibm: + +IBM Watson Language Translator +------------------------------ + +.. versionremoved:: 5.13.1 + + This service was withdrawn by vendor as of 10 December 2024. + +.. AUTOGENERATED START: libretranslate +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-libretranslate: + +LibreTranslate +-------------- + +.. versionadded:: 4.7.1 + +:Service ID: ``libretranslate`` +:Maximal score: 89 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``url`` | API URL | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: libretranslate + +LibreTranslate is a free and open-source service for machine translations. The +public instance requires an API key, but LibreTranslate can be self-hosted +and there are several mirrors available to use the API for free. + +``https://libretranslate.com/`` (official public instance) + Requires an API key to use outside of the website. + +.. seealso:: + + * `LibreTranslate website `_ + * `LibreTranslate repository `_ + * :ref:`docker-libretranslate` + + +.. + # spellchecker:off + +.. AUTOGENERATED START: microsoft-translator +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-microsoft-translator: + +Azure AI Translator +------------------- + +:Service ID: ``microsoft-translator`` +:Maximal score: 90 +:Advanced features: * :ref:`placeables-mt` + * :ref:`glossary-mt` +:Configuration: +---------------------+-------------------------------+---------------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+-------------------------------+---------------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+-------------------------------+---------------------------------------------------------------------------+ + | ``base_url`` | Application base URL | Available choices: | + | | | | + | | | ``api.cognitive.microsofttranslator.com`` -- Global (non-regional) | + | | | | + | | | ``api-apc.cognitive.microsofttranslator.com`` -- Asia Pacific | + | | | | + | | | ``api-eur.cognitive.microsofttranslator.com`` -- Europe | + | | | | + | | | ``api-nam.cognitive.microsofttranslator.com`` -- North America | + | | | | + | | | ``api.translator.azure.cn`` -- China | + | | | | + | | | ``api.cognitive.microsofttranslator.us`` -- Azure US Government cloud | + +---------------------+-------------------------------+---------------------------------------------------------------------------+ + | ``endpoint_url`` | Authentication service URL | Regional or multi-service can be specified using region field below. | + | | | | + | | | Available choices: | + | | | | + | | | ``api.cognitive.microsoft.com`` -- Global | + | | | | + | | | ``api.cognitive.azure.cn`` -- China | + | | | | + | | | ``api.cognitive.microsoft.us`` -- Azure US Government cloud | + +---------------------+-------------------------------+---------------------------------------------------------------------------+ + | ``region`` | Authentication service region | | + +---------------------+-------------------------------+---------------------------------------------------------------------------+ + | ``category`` | Category | Specify a customized system category ID to use it instead of general one. | + +---------------------+-------------------------------+---------------------------------------------------------------------------+ + + +.. AUTOGENERATED END: microsoft-translator + +.. + # spellchecker:on + +Machine translation service provided by Microsoft in Azure portal as a one of +Cognitive Services. + +Weblate implements Translator API V3. + +The service automatically uses :ref:`glossary` via `dynamic dictionary `_, see :ref:`glossary-mt`. + +Translator Text API V2 +`````````````````````` +The key you use with Translator API V2 can be used with API 3. + +Translator Text API V3 +`````````````````````` +You need to register at Azure portal and use the key you obtain there. +With new Azure keys, you also need to set ``region`` to locale of your service. + +You can also specify a custom category to use `custom translator `_. + +.. hint:: + + For Azure China, please use your endpoint from the Azure Portal. + +.. seealso:: + + * `Cognitive Services - Text Translation API `_ + * `Microsoft Azure Portal `_ + * `Base URLs `_ + * `"Authenticating with a Multi-service resource" `_ + * `"Authenticating with an access token" section `_ + + +.. AUTOGENERATED START: modernmt +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-modernmt: + +ModernMT +-------- + +.. versionadded:: 4.2 + +:Service ID: ``modernmt`` +:Maximal score: 90 +:Advanced features: * :ref:`glossary-mt` +:Configuration: +---------------------+---------------------------+-----------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+-----------------------------------------------------------------------+ + | ``url`` | API URL | | + +---------------------+---------------------------+-----------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+-----------------------------------------------------------------------+ + | ``context_vector`` | Context vector | Comma-separated list of memory IDs:weight. e.g: 1234:0.123,4567:0.456 | + +---------------------+---------------------------+-----------------------------------------------------------------------+ + + +.. AUTOGENERATED END: modernmt + +The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. + +.. seealso:: + + `ModernMT API `_ + + +.. AUTOGENERATED START: mymemory +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-mymemory: + +MyMemory +-------- + +:Service ID: ``mymemory`` +:Maximal score: 100 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``email`` | Contact e-mail | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``username`` | Username | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: mymemory + +Huge translation memory with machine translation. + +Free, anonymous usage is currently limited to 100 requests/day, or to 1000 +requests/day when you provide a contact e-mail address in ``email``. +You can also ask them for more. + + +.. seealso:: + + `MyMemory website `_ + + +.. AUTOGENERATED START: netease-sight +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-netease-sight: + +Netease Sight +------------- + +:Service ID: ``netease-sight`` +:Maximal score: 90 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | Client ID | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``secret`` | Client secret | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: netease-sight + +Machine translation service provided by NetEase. + +This service uses an API, and you need to obtain key and secret from NetEase. + +.. seealso:: + + `NetEase Sight Translation Platform `_ + + +.. AUTOGENERATED START: ollama +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-ollama: + +Ollama +------ + +.. versionadded:: 5.15 + +:Service ID: ``ollama`` +:Maximal score: 90 +:Advanced features: * :ref:`glossary-mt` +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``base_url`` | API URL | Base URL of the Ollama API, localhost and port 11434 by default. | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``model`` | Ollama model | Name of the model described in Ollama catalogue. | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``persona`` | Translator persona | Describe the persona of translator to improve the accuracy of the translation. For example: “You are a squirrel breeder.” | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``style`` | Translator style | Describe the style of translation. For example: “Use informal language.” | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + + +.. AUTOGENERATED END: ollama + +Performs translation using `Ollama`_ models. + +The Ollama API allows for the use of open source models for translations +either locally installed or remotely accessed via the `Ollama`_ service. +Note that before configuring your models, you should have `Ollama installed`_ +and downloaded the models you wish to use. + +Use persona and style fields to further fine-tune translations. These will be +used in a prompt for Ollama and allow you to change the style of the +translations. + +The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. + +.. seealso:: + + * `Ollama models `_ + +.. _Ollama: https://ollama.com/ +.. _Ollama installed: https://ollama.com/download + + +.. AUTOGENERATED START: openai +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-openai: + +OpenAI +------ + +.. versionadded:: 5.3 + +:Service ID: ``openai`` +:Maximal score: 90 +:Advanced features: * :ref:`glossary-mt` +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``base_url`` | OpenAI API base URL | Base URL of the OpenAI API, if it differs from the OpenAI default URL | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``model`` | OpenAI model | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``gpt-5-nano`` -- GPT-5-nano | + | | | | + | | | ``gpt-5-mini`` -- GPT-5-mini | + | | | | + | | | ``gpt-5.2`` -- GPT-5.2 | + | | | | + | | | ``gpt-5.1`` -- GPT-5.1 | + | | | | + | | | ``gpt-5`` -- GPT-5 | + | | | | + | | | ``gpt-4.1-nano`` -- GPT-4.1-nano | + | | | | + | | | ``gpt-4.1-mini`` -- GPT-4.1-mini | + | | | | + | | | ``gpt-4.1`` -- GPT-4.1 | + | | | | + | | | ``gpt-4o-mini`` -- GPT-4o mini | + | | | | + | | | ``gpt-4o`` -- GPT-4o | + | | | | + | | | ``o3-mini`` -- o3-mini | + | | | | + | | | ``o3`` -- o3 | + | | | | + | | | ``o1-mini`` -- o1-mini | + | | | | + | | | ``o1`` -- o1 | + | | | | + | | | ``o1-pro`` -- o1-pro | + | | | | + | | | ``custom`` -- Custom model | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``persona`` | Translator persona | Describe the persona of translator to improve the accuracy of the translation. For example: “You are a squirrel breeder.” | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``style`` | Translator style | Describe the style of translation. For example: “Use informal language.” | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + | ``custom_model`` | Custom model name | Only needed when model is set to 'Custom model' | + +---------------------+---------------------------+---------------------------------------------------------------------------------------------------------------------------+ + + +.. AUTOGENERATED END: openai + +Performs translation using `OpenAI`_. + +The OpenAI API is powered by a diverse set of models with different +capabilities and price points. Automatic selection chooses the best model +available, but you might want to choose a specific model that matches your needs. + +Use persona and style fields to further fine-tune translations. These will be +used in a prompt for OpenAI and allow you to change the style of the +translations. + +The service automatically uses :ref:`glossary`, see :ref:`glossary-mt`. + +.. versionchanged:: 5.7 + + Support for custom model and base URL was added. + +.. seealso:: + + * `OpenAI models `_ + * `OpenAI API keys `_ + +.. _OpenAI: https://openai.com/ + +.. AUTOGENERATED START: sap-translation-hub +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-sap-translation-hub: + +SAP Translation Hub +------------------- + +:Service ID: ``sap-translation-hub`` +:Maximal score: 100 +:Configuration: +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``url`` | API URL | | + +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``username`` | SAP username | | + +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``password`` | SAP password | | + +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``enable_mt`` | Enable machine translation | | + +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ + | ``domain`` | Translation domain | The ID of a translation domain, for example, BC. If you do not specify a domain, the method searches for translations in all available domains. | + +---------------------+----------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ + + +.. AUTOGENERATED END: sap-translation-hub + +Machine translation service provided by SAP. + +You need to have a SAP account (and the SAP Translation Hub enabled in the SAP Cloud +Platform) to use this service. + +You can also configure whether to also use machine translation services, in +addition to the term database. + +.. note:: + + To access the Sandbox API, you need to set ``url`` + and ``key``. + + To access the productive API, you need to set ``url``, ``username`` and ``password``. + +.. seealso:: + + * `What is SAP Translation Hub `_ + * `SAP Translation Hub API `_ + + +.. AUTOGENERATED START: systran +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-systran: + +Systran +------- + +:Service ID: ``systran`` +:Maximal score: 90 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: systran + +Machine translation service provided by Systran. + +This service uses an API, and you need to obtain API key at . + +.. AUTOGENERATED START: tmserver +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-tmserver: + +tmserver +-------- + +:Service ID: ``tmserver`` +:Maximal score: 100 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``url`` | API URL | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: tmserver + +You can run your own translation memory server by using a tmserver protocol. + +* The original :program:`tmserver` was bundled with the translate-toolkit. +* amaGama server is an enhanced version of tmserver. + +.. note:: + + There currently does not seem to be a maintained server for this. + + +.. AUTOGENERATED START: weblate +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-weblate: + +Weblate +------- + +:Service ID: ``weblate`` +:Maximal score: 100 +:Configuration: `This service has no configuration.` + +.. AUTOGENERATED END: weblate + +Weblate machine translation service can provide translations based +on the exact matches of a string in the currently existing strings +in a :guilabel:`Translated`, :guilabel:`Approved`, +or :guilabel:`Read-only` :ref:`states ` inside Weblate. + +.. AUTOGENERATED START: weblate-translation-memory +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-weblate-translation-memory: + +Weblate Translation Memory +-------------------------- + +:Service ID: ``weblate-translation-memory`` +:Maximal score: 100 +:Configuration: `This service has no configuration.` + +.. AUTOGENERATED END: weblate-translation-memory + +Use :ref:`translation-memory` as a machine translation service. +Any string that has been translated before (or uploaded to the +translation memory) can be translated in this way. +This suggestion source works with fuzzy matching. + +.. note:: + + Recreating :ref:`translation-memory` reduces capabilities of this TM source. + + +.. AUTOGENERATED START: yandex +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-yandex: + +Yandex +------ + +:Service ID: ``yandex`` +:Maximal score: 90 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: yandex + +Machine translation service provided by Yandex. + +This service uses a Translation API, and you need to obtain an API key from Yandex. + +.. seealso:: + + * `Yandex Translate API `_ + * `Powered by Yandex.Translate `_ + + +.. AUTOGENERATED START: yandex-v2 +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-yandex-v2: + +Yandex v2 +--------- + +.. versionadded:: 5.1 + +:Service ID: ``yandex-v2`` +:Maximal score: 90 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | API key | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: yandex-v2 + +Machine translation service provided by Yandex. + +This service uses a Translation API, and you need to obtain an API key from Yandex Cloud. + +.. seealso:: + + * `Yandex Translate API v2 `_ + * `Powered by Yandex.Cloud `_ + +.. AUTOGENERATED START: youdao-zhiyun +.. This section is automatically generated by `./manage.py list_machinery`. Do not edit manually. + +.. _mt-youdao-zhiyun: + +Youdao Zhiyun +------------- + +:Service ID: ``youdao-zhiyun`` +:Maximal score: 90 +:Configuration: +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``source_language`` | Source language selection | Available choices: | + | | | | + | | | ``auto`` -- Automatic selection | + | | | | + | | | ``source`` -- Component source language | + | | | | + | | | ``secondary`` -- Secondary language defined in project or component | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``key`` | Client ID | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + | ``secret`` | Client secret | | + +---------------------+---------------------------+---------------------------------------------------------------------+ + + +.. AUTOGENERATED END: youdao-zhiyun + +Machine translation service provided by Youdao. + +This service uses an API, and you need to obtain an ID and an API key from Youdao. + +.. seealso:: + + `Youdao Zhiyun Natural Language Translation Service `_ diff --git a/docs/user/checks.rst b/docs/user/checks.rst index bc8049c2837a..254976374cc8 100644 --- a/docs/user/checks.rst +++ b/docs/user/checks.rst @@ -103,2167 +103,5 @@ Please file a bug if anything is reported in error. * :setting:`CHECK_LIST` * :ref:`custom-checks` -Translation checks ------------------- -Executed upon every translation change, helping translators maintain -good quality translations. - -.. _check-bbcode: - -BBCode markup -~~~~~~~~~~~~~ - - -:Summary: BBCode in translation does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.markup.BBCodeCheck`` -:Check identifier: ``bbcode`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``bbcode-text`` -:Flag to ignore: ``ignore-bbcode`` - -.. versionchanged:: 5.10 - -This checks no longer relies on unreliable automatic detection, it now needs to be turned on using the ``bbcode-text`` flag. - - -BBCode represents simple markup, like for example highlighting important parts of a -message in bold font, or italics. - -This check ensures they are also found in translation. - -.. note:: - - The method for detecting BBCode is currently quite simple so this check - might produce false positives. - -.. _check-duplicate: - -Consecutive duplicated words -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 4.1 - -:Summary: Text contains the same word twice in a row. -:Scope: translated strings -:Check class: ``weblate.checks.duplicate.DuplicateCheck`` -:Check identifier: ``duplicate`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-duplicate`` - -Checks that no consecutive duplicate words occur in a translation. This usually -indicates a mistake in the translation. - -.. hint:: - - This check includes language specific rules to avoid false positives. In - case it triggers falsely in your case, let us know. See :ref:`report-issue`. - -.. _check-check-glossary: - -Does not follow glossary -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 4.5 - -:Summary: The translation does not follow terms defined in a glossary. -:Scope: translated strings -:Check class: ``weblate.checks.glossary.GlossaryCheck`` -:Check identifier: ``check_glossary`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``check-glossary`` -:Flag to ignore: ``ignore-check-glossary`` - -This check has to be turned on using ``check-glossary`` flag (see -:ref:`custom-checks`). Please consider following prior to enabling it: - -* It does exact string matching, the glossary is expected to contain terms in all variants. -* Checking each string against glossary is expensive, it will slow down any operation in Weblate which involves running checks like importing strings or translating. -* It also utilizes untranslatable glossary terms in :ref:`check-same`. - -.. seealso:: - - * :ref:`glossary` - * :ref:`custom-checks` - * :ref:`component-check_flags` - -.. _check-double-space: - -Double space -~~~~~~~~~~~~ - - -:Summary: Translation contains double space. -:Scope: translated strings -:Check class: ``weblate.checks.chars.DoubleSpaceCheck`` -:Check identifier: ``double_space`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-double-space`` - -Checks that double space is present in translation to avoid false positives on other space-related checks. - -Check is false when double space is found in source meaning double space is intentional. - -.. _check-fluent-parts: - -Fluent parts -~~~~~~~~~~~~ - -.. versionadded:: 5.0 - -:Summary: Fluent parts should match. -:Scope: translated strings -:Check class: ``weblate.checks.fluent.parts.FluentPartsCheck`` -:Check identifier: ``fluent-parts`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`fluent` -:Flag to enable: ``fluent-parts`` -:Flag to ignore: ``ignore-fluent-parts`` - -Each Fluent Message can have an optional value (the main text content), and -optional attributes, each of which is a "part" of the Message. In Weblate, all -these parts appear within the same block, using Fluent-like syntax to specify -the attributes. For example: - -.. code-block:: text - - This is the Message value - .title = This is the title attribute - .alt = This is the alt attribute - -This check ensures that the translated Message also has a value if the source -Message has one, or no value if the source has none. This also checks that the -same attributes used in the source Message also appear in the translation, with -no additions. - -.. note:: - - This check is not applied to Fluent Terms since Terms always have a value, and - Term attributes tend to be locale-specific (used for grammar rules, etc.), and - are not expected to appear in all translations. - -.. seealso:: - - `Fluent Attributes `_ - -.. _check-fluent-references: - -Fluent references -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 5.0 - -:Summary: Fluent references should match. -:Scope: translated strings -:Check class: ``weblate.checks.fluent.references.FluentReferencesCheck`` -:Check identifier: ``fluent-references`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`fluent` -:Flag to enable: ``fluent-references`` -:Flag to ignore: ``ignore-fluent-references`` - -A Fluent Message or Term can reference another Message, Term, Attribute, or a -variable. For example: - -.. code-block:: text - - Here is a { message }, a { message.attribute } a { -term } and a { $variable }. - Within a function { NUMBER($num, minimumFractionDigits: 2) } - -Generally, translated Messages or Terms are expected to contain the same -references as the source, although not necessarily in the same order of -appearance. So this check ensures that translations use the same references in -their value as the source value, the same number of times, and with no -additions. For Messages, this will also check that each Attribute in the -translation uses the same references as the matching Attribute in the source. - -When the source or translation contains Fluent Select Expressions, then each -possible variant in the source must be matched with at least one variant in the -translation with the same references, and vice versa. - -Moreover, if a variable reference appears both in the Select Expression's -selector and within one of its variants, then all variants may also be -considered as if they also contain that reference. The assumption being that the -variant's key may have made the reference redundant for that variant. For -example: - -.. code-block:: text - - { $num -> - [one] an apple - *[other] { $num } apples - } - -Here, for the purposes of this check, the ``[one]`` variant will also be -considered to contain the ``$num`` reference. - -However, a reference within the Select Expression's selector, which can only be -a variable of a Term Attribute in Fluent's syntax, will not by itself count as a -required reference because they do not form the actual text content of the -string that the end-user will see, and the presence of a Select Expression is -considered locale-specific. For example: - -.. code-block:: text - - { -term.starts-with-vowel -> - [yes] an { -term } - *[no] a { -term } - } - -Here a reference to ``-term.starts-with-vowel`` is not expected to appear in -translations, but a reference to ``-term`` is. - -.. seealso:: - - `Fluent Variables `_ - `Fluent Message and Term references `_ - `Fluent Select Expressions `_ - -.. _check-fluent-target-inner-html: - -Fluent translation inner HTML -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 5.0 - -:Summary: Fluent target should be valid inner HTML that matches. -:Scope: translated strings -:Check class: ``weblate.checks.fluent.inner_html.FluentTargetInnerHTMLCheck`` -:Check identifier: ``fluent-target-inner-html`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`fluent` -:Flag to enable: ``fluent-target-inner-html`` -:Flag to ignore: ``ignore-fluent-target-inner-html`` - -This check will verify that the translated value of a Message or Term contains -the same HTML elements as the source value. - -First, if the source value fails the :ref:`check-fluent-source-inner-html` -check, then this check will do nothing. Otherwise, the translated value will -also be checked under the same conditions. - -Second, the HTML elements found in the translated value will be compared against -the HTML elements found in the source value. Two elements will match if they -share the exact same tag name, the exact same attributes and values, and all -their ancestors match in the same way. This check will ensure that all the -elements in the source appear somewhere in the translation, with the same -*number* of appearances, and with no additional elements added. When there are -multiple elements in the value, they need not appear in the same order in the -translation value. - -When the source or translation contains Fluent Select Expressions, then each -possible variant in the source must be matched with at least one variant in the -translation with the same HTML elements, and vice versa. - -When using Fluent in combination with the Fluent DOM package, this check will -ensure that the translation also includes any required ``data-l10n-name`` -elements that appear in the source, or any of the allowed inline elements like -``
``. - -For example, the following source: - -.. code-block:: text - - Source message with icon - -would match with: - -.. code-block:: text - - Translated message with icon - -but not: - -.. code-block:: text - - Translated message with icon - -nor - -.. code-block:: text - - Translated message
with no icon - -.. seealso:: - - * :ref:`check-fluent-source-inner-html` - * `Fluent DOM `_ - -.. _check-fluent-target-syntax: - -Fluent translation syntax -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 5.0 - -:Summary: Fluent syntax error in the translation. -:Scope: translated strings -:Check class: ``weblate.checks.fluent.syntax.FluentTargetSyntaxCheck`` -:Check identifier: ``fluent-target-syntax`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`fluent` -:Flag to enable: ``fluent-target-syntax`` -:Flag to ignore: ``ignore-fluent-target-syntax`` - -In Weblate, Fluent strings use Fluent syntax for references and variables, but -also for more complex features like defining attributes and selector variants, -including plurals. This check ensures that the syntax used in the translation -will be valid for Fluent. - -.. seealso:: - - * :ref:`check-fluent-source-syntax` - * `Fluent Syntax Guide `_ - * `Mozilla Basic Syntax Guide `_ - -.. _check-formats: - -Formatted strings -~~~~~~~~~~~~~~~~~ - -Checks that the formatting in strings is replicated between both source and translation. -Omitting format strings in translation usually causes severe problems, so the formatting in strings -should usually match the source. - -Weblate supports checking format strings in several languages. The check is not -enabled automatically, only if a string is flagged appropriately (e.g. -`c-format` for C format). Gettext adds this automatically, but you will -probably have to add it manually for other file formats or if your PO files are -not generated by :program:`xgettext`. - -Most of the format checks allow omitting format strings for plural forms having -a single count. This allows translators to write nicer strings for these cases -(`One apple` instead of `%d apple`). Turn this off by adding ``strict-format`` flag. - -The flags can be customized per string (see :ref:`additional`) or in a :ref:`component`. -Having it defined per component is simpler, but it can lead to false positives in -case the string is not interpreted as a formatting string, but format string syntax -happens to be used. - -.. hint:: - - In case specific format check is not available in Weblate, you can use - generic :ref:`check-placeholders`. - -Besides checking, this will also highlight the formatting strings to easily -insert them into translated strings: - -.. image:: /screenshots/format-highlight.webp - -.. _check-angularjs-format: - -AngularJS interpolation string -****************************** - - -:Summary: AngularJS interpolation strings do not match source. -:Scope: translated strings -:Check class: ``weblate.checks.angularjs.AngularJSInterpolationCheck`` -:Check identifier: ``angularjs_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``angularjs-format`` -:Flag to ignore: ``ignore-angularjs-format`` -:Named format string example: ``Your balance is {{amount}} {{ currency }}`` - -.. seealso:: - - * :ref:`check-formats` - * `AngularJS text interpolation `_ - -.. _check-automattic-components-format: - -Automattic components formatting -******************************** - - -:Summary: The Automattic components' placeholders do not match the source. -:Scope: translated strings -:Check class: ``weblate.checks.format.AutomatticComponentsCheck`` -:Check identifier: ``automattic_components_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``automattic-components-format`` -:Flag to ignore: ``ignore-automattic-components-format`` -:Simple format string example: ``They bought {{strong}}apples{{/strong}}.`` - -.. seealso:: - - * :ref:`check-formats` - * `Interpolate Components `_ - -.. _check-c-format: - -C format -******** - - -:Summary: C format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.CFormatCheck`` -:Check identifier: ``c_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``c-format`` -:Flag to ignore: ``ignore-c-format`` -:Simple format string example: ``There are %d apples`` -:Position format string example: ``Your balance is %1$d %2$s`` - -.. seealso:: - - * :ref:`check-formats` - * `C format strings `_ - * `C printf format `_ - -.. _check-c-sharp-format: - -C# format -********* - - -:Summary: C# format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.CSharpFormatCheck`` -:Check identifier: ``c_sharp_format`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`resourcedictionary` -:Flag to enable: ``c-sharp-format``, ``csharp-format`` -:Flag to ignore: ``ignore-c-sharp-format`` -:Position format string example: ``There are {0} apples`` - -.. seealso:: - - * :ref:`check-formats` - * `C# String Format `_ - -.. _check-es-format: - -ECMAScript template literals -**************************** - - -:Summary: ECMAScript template literals do not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.ESTemplateLiteralsCheck`` -:Check identifier: ``es_format`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`mi18n-lang` -:Flag to enable: ``es-format`` -:Flag to ignore: ``ignore-es-format`` -:Interpolation example: ``There are ${number} apples`` - -.. seealso:: - - * :ref:`check-formats` - * `Template literals `_ - -.. _check-i18next-interpolation: - -i18next interpolation -********************* - -.. versionadded:: 4.0 - -:Summary: The i18next interpolation does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.I18NextInterpolationCheck`` -:Check identifier: ``i18next_interpolation`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`i18next`, :ref:`i18nextv4` -:Flag to enable: ``i18next-interpolation`` -:Flag to ignore: ``ignore-i18next-interpolation`` -:Interpolation example: ``There are {{number}} apples`` -:Nesting example: ``There are $t(number) apples`` - -.. seealso:: - - * :ref:`check-formats` - * `i18next interpolation `_ - - -.. _check-icu-message-format: - -ICU MessageFormat -***************** - -.. versionadded:: 4.9 - -:Summary: Syntax errors and/or placeholder mismatches in ICU MessageFormat strings. -:Scope: translated strings -:Check class: ``weblate.checks.icu.ICUMessageFormatCheck`` -:Check identifier: ``icu_message_format`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`arb`, :ref:`formatjs` -:Flag to enable: ``icu-message-format`` -:Flag to ignore: ``ignore-icu-message-format`` -:Interpolation example: ``There {number, plural, one {is one apple} other {are # apples}}.`` - -This check has support for both pure ICU MessageFormat messages as well as ICU with simple -XML tags. You can configure the behavior of this check by using ``icu-flags:*``, either by -opting into XML support or by disabling certain sub-checks. For example, the following flag -enables XML support while disabling validation of plural sub-messages: - -.. code-block:: text - - icu-message-format, icu-flags:xml:-plural_selectors - -+---------------------------+------------------------------------------------------------+ -| ``xml`` | Enable support for simple XML tags. By default, XML tags | -| | are parsed loosely. Stray ``<`` characters are ignored | -| | if they are not reasonably part of a tag. | -+---------------------------+------------------------------------------------------------+ -| ``strict-xml`` | Enable support for strict XML tags. All ``<`` characters | -| | must be escaped if they are not part of a tag. | -+---------------------------+------------------------------------------------------------+ -| ``-highlight`` | Disable highlighting placeholders in the editor. | -+---------------------------+------------------------------------------------------------+ -| ``-require_other`` | Disable requiring sub-messages to have an ``other`` | -| | selector. | -+---------------------------+------------------------------------------------------------+ -| ``-submessage_selectors`` | Skip checking that sub-message selectors match the source. | -+---------------------------+------------------------------------------------------------+ -| ``-types`` | Skip checking that placeholder types match the source. | -+---------------------------+------------------------------------------------------------+ -| ``-extra`` | Skip checking that no placeholders are present that were | -| | not present in the source string. | -+---------------------------+------------------------------------------------------------+ -| ``-missing`` | Skip checking that no placeholders are missing that were | -| | present in the source string. | -+---------------------------+------------------------------------------------------------+ - -Additionally, when ``strict-xml`` is not enabled but ``xml`` is enabled, you can use the -``icu-tag-prefix:PREFIX`` flag to require that all XML tags start with a specific string. -For example, the following flag will only allow XML tags to be matched if they start with -``click here`` but not ``this``. - -.. seealso:: - - * :ref:`check-icu-message-format-syntax` - * :ref:`check-formats` - * `ICU: Formatting Messages `_ - * `Format.JS: Message Syntax `_ - - -.. _check-java-printf-format: - -Java format -*********** - -:Summary: Java format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.JavaFormatCheck`` -:Check identifier: ``java_printf_format`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`aresource`, :ref:`moko-resource`, :ref:`cmp-resource` -:Flag to enable: ``java-printf-format`` -:Flag to ignore: ``ignore-java-printf-format`` -:Simple format string example: ``There are %d apples`` -:Position format string example: ``Your balance is %1$d %2$s`` - -.. versionchanged:: 4.14 - - This used to be toggled by the ``java-format`` flag, it was changed for consistency with GNU gettext. - -.. seealso:: - - * :ref:`check-formats` - * `Java Format Strings `_ - - -.. _check-java-format: - -Java MessageFormat -****************** - - -:Summary: Java MessageFormat string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.JavaMessageFormatCheck`` -:Check identifier: ``java_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``java-format``, ``auto-java-messageformat`` enables check only if there is a format string in the source -:Flag to ignore: ``ignore-java-format`` -:Position format string example: ``There are {0} apples`` - -.. versionchanged:: 4.14 - - This used to be toggled by ``java-messageformat`` flag, it was changed for consistency with GNU gettext. - -This check validates that format string is valid for the Java MessageFormat -class. Besides matching format strings in the curly braces, it also verifies -single quotes as they have a special meaning. Whenever writing single quote, it -should be written as ``''``. When not paired, it is treated as beginning of -quoting and will not be shown when rendering the string. - -.. seealso:: - - * :ref:`check-formats` - * `Java MessageFormat `_ - -.. _check-javascript-format: - -JavaScript format -***************** - - -:Summary: JavaScript format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.JavaScriptFormatCheck`` -:Check identifier: ``javascript_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``javascript-format`` -:Flag to ignore: ``ignore-javascript-format`` -:Simple format string example: ``There are %d apples`` - -.. seealso:: - - * :ref:`check-formats` - * `JavaScript formatting strings `_ - -.. _check-laravel-format: - -Laravel format -************** - - -:Summary: Laravel format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.LaravelFormatCheck`` -:Check identifier: ``laravel_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``laravel-format`` -:Flag to ignore: ``ignore-laravel-format`` -:Named format string example: ``The :attribute must be :value`` - -.. seealso:: - - * :ref:`check-formats` - * `Laravel translation formatting `_ - -.. _check-lua-format: - -Lua format -********** - - -:Summary: Lua format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.LuaFormatCheck`` -:Check identifier: ``lua_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``lua-format`` -:Flag to ignore: ``ignore-lua-format`` -:Simple format string example: ``There are %d apples`` - -.. seealso:: - - * :ref:`check-formats` - * `Lua formatting strings `_ - -.. _check-object-pascal-format: - -Object Pascal format -******************** - - -:Summary: Object Pascal format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.ObjectPascalFormatCheck`` -:Check identifier: ``object_pascal_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``object-pascal-format`` -:Flag to ignore: ``ignore-object-pascal-format`` -:Simple format string example: ``There are %d apples`` - -.. seealso:: - - * :ref:`check-formats` - * `Object Pascal formatting strings `_ - * `Free Pascal formatting strings `_ - * `Delphi formatting strings `_ - -.. _check-percent-placeholders: - -Percent placeholders -******************** - -.. versionadded:: 4.0 - -:Summary: The percent placeholders do not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.PercentPlaceholdersCheck`` -:Check identifier: ``percent_placeholders`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``percent-placeholders`` -:Flag to ignore: ``ignore-percent-placeholders`` -:Simple format string example: ``There are %number% apples`` - -.. seealso:: - - :ref:`check-formats` - -.. _check-perl-brace-format: - -Perl brace format -***************** - - -:Summary: Perl brace format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.PerlBraceFormatCheck`` -:Check identifier: ``perl_brace_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``perl-brace-format`` -:Flag to ignore: ``ignore-perl-brace-format`` -:Named format string example: ``There are {number} apples`` - -.. seealso:: - - * :ref:`check-formats` - * `Perl Format Strings `_ - -.. _check-perl-format: - -Perl format -*********** - - -:Summary: Perl format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.PerlFormatCheck`` -:Check identifier: ``perl_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``perl-format`` -:Flag to ignore: ``ignore-perl-format`` -:Simple format string example: ``There are %d apples`` -:Position format string example: ``Your balance is %1$d %2$s`` - -.. seealso:: - - * :ref:`check-formats` - * `Perl sprintf `_ - * `Perl Format Strings `_ - -.. _check-php-format: - -PHP format -********** - - -:Summary: PHP format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.PHPFormatCheck`` -:Check identifier: ``php_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``php-format`` -:Flag to ignore: ``ignore-php-format`` -:Simple format string example: ``There are %d apples`` -:Position format string example: ``Your balance is %1$d %2$s`` - -.. seealso:: - - * :ref:`check-formats` - * `PHP sprintf documentation `_ - * `PHP Format Strings `_ - -.. _check-python-brace-format: - -Python brace format -******************* - - -:Summary: Python brace format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.PythonBraceFormatCheck`` -:Check identifier: ``python_brace_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``python-brace-format`` -:Flag to ignore: ``ignore-python-brace-format`` -:Simple format string: ``There are {} apples`` -:Named format string example: ``Your balance is {amount} {currency}`` - -.. seealso:: - - * :ref:`check-formats` - * :ref:`Python brace format ` - * `Python Format Strings `_ - -.. _check-python-format: - -Python format -************* - - -:Summary: Python format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.PythonFormatCheck`` -:Check identifier: ``python_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``python-format`` -:Flag to ignore: ``ignore-python-format`` -:Simple format string: ``There are %d apples`` -:Named format string example: ``Your balance is %(amount)d %(currency)s`` - -.. seealso:: - - * :ref:`check-formats` - * :ref:`Python string formatting ` - * `Python Format Strings `_ - -.. _check-qt-format: - -Qt format -********* - - -:Summary: Qt format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.qt.QtFormatCheck`` -:Check identifier: ``qt_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``qt-format`` -:Flag to ignore: ``ignore-qt-format`` -:Position format string example: ``There are %1 apples`` - -.. seealso:: - - * :ref:`check-formats` - * `Qt QString::arg() `_ - -.. _check-qt-plural-format: - -Qt plural format -**************** - - -:Summary: Qt plural format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.qt.QtPluralCheck`` -:Check identifier: ``qt_plural_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``qt-plural-format`` -:Flag to ignore: ``ignore-qt-plural-format`` -:Plural format string example: ``There are %Ln apple(s)`` - -.. seealso:: - - * :ref:`check-formats` - * `Qt i18n guide `_ - -.. _check-ruby-format: - -Ruby format -*********** - - -:Summary: Ruby format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.ruby.RubyFormatCheck`` -:Check identifier: ``ruby_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``ruby-format`` -:Flag to ignore: ``ignore-ruby-format`` -:Simple format string example: ``There are %d apples`` -:Position format string example: ``Your balance is %1$f %2$s`` -:Named format string example: ``Your balance is %+.2f %s`` -:Named template string: ``Your balance is %{amount} %{currency}`` - -.. seealso:: - - * :ref:`check-formats` - * `Ruby Kernel#sprintf `_ - -.. _check-scheme-format: - -Scheme format -************* - - -:Summary: Scheme format string does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.SchemeFormatCheck`` -:Check identifier: ``scheme_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``scheme-format`` -:Flag to ignore: ``ignore-scheme-format`` -:Simple format string example: ``There are ~d apples`` - -.. seealso:: - - * :ref:`check-formats` - * `Srfi 28 `_ - * `Chicken Scheme format `_ - * `Guile Scheme formatted output `_ - -.. _check-vue-format: - -Vue I18n formatting -******************* - - -:Summary: The Vue I18n formatting does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.format.VueFormattingCheck`` -:Check identifier: ``vue_format`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``vue-format`` -:Flag to ignore: ``ignore-vue-format`` -:Named formatting: ``There are {count} apples`` -:Rails i18n formatting: ``There are %{count} apples`` -:Linked locale messages: ``@:message.dio @:message.the_world!`` - -.. seealso:: - - * :ref:`check-formats` - * `Vue I18n Formatting `_ - * `Vue I18n Linked locale messages `_ - -.. _check-translated: - -Has been translated -~~~~~~~~~~~~~~~~~~~ - - -:Summary: This string has been translated in the past. -:Scope: all strings -:Check class: ``weblate.checks.consistency.TranslatedCheck`` -:Check identifier: ``translated`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-translated`` - -Means a string has been translated already. This can happen when the -translations have been reverted in VCS or lost otherwise. - -.. _check-inconsistent: - -Inconsistent -~~~~~~~~~~~~ - - -:Summary: This string has more than one translation in this project or is untranslated in some components. -:Scope: all strings -:Check class: ``weblate.checks.consistency.ConsistencyCheck`` -:Check identifier: ``inconsistent`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-inconsistent`` - -Weblate checks translations of the same string across all translation within a -project to help you keep consistent translations. - -The check fails on differing translations of one string within a project. This -can also lead to inconsistencies in displayed checks. You can find other -translations of this string on the :guilabel:`Other occurrences` tab. - -This check applies to all components in a project that have -:ref:`component-allow_translation_propagation` turned on. - -.. hint:: - - For performance reasons, the check might not find all inconsistencies, it - limits number of matches. - -.. note:: - - This check also fires in case the string is translated in one component and - not in another. It can be used as a quick way to manually handle strings - which are untranslated in some components just by clicking on the - :guilabel:`Use this translation` button displayed on each line in the - :guilabel:`Other occurrences` tab. - - You can use :ref:`addon-weblate.autotranslate.autotranslate` add-on to - automate translating of newly added strings which are already translated in - another component. - -.. seealso:: - - :ref:`translation-consistency` - -.. _check-rst-references: - -Inconsistent reStructuredText -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 5.10 - -:Summary: Inconsistent reStructuredText markup in the translated message. -:Scope: translated strings -:Check class: ``weblate.checks.markup.RSTReferencesCheck`` -:Check identifier: ``rst-references`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``rst-text`` -:Flag to ignore: ``ignore-rst-references`` - -reStructuredText term references or other markup do not match source, the typical causes for these errors are: - -* Mismatched or missing backticks. -* Missing spaces or interpunction around the reference. The reStructuredText inline blocks need to be separated by non-word characters. -* Space between inline tag and backticks. -* The reference name is not being translated. -* Using quotes instead of backticks. -* Mismatched substitutions or footnote references. - -.. seealso:: - - * `reStructuredText Primer`_ - * :ref:`check-rst-syntax` - -.. _check-kashida: - -Kashida letter used -~~~~~~~~~~~~~~~~~~~ - - -:Summary: The decorative kashida letters should not be used. -:Scope: translated strings -:Check class: ``weblate.checks.chars.KashidaCheck`` -:Check identifier: ``kashida`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-kashida`` - - -The decorative Kashida letters should not be used in translation. These are -also known as Tatweel. - -.. seealso:: - - `Kashida on Wikipedia `_ - -.. _check-md-link: - -Markdown links -~~~~~~~~~~~~~~ - - -:Summary: Markdown links do not match source. -:Scope: translated strings -:Check class: ``weblate.checks.markup.MarkdownLinkCheck`` -:Check identifier: ``md-link`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`markdown` -:Flag to enable: ``md-text`` -:Flag to ignore: ``ignore-md-link`` - -Markdown links do not match source. - -.. seealso:: - - `Markdown links `_ - - -.. _check-md-reflink: - -Markdown references -~~~~~~~~~~~~~~~~~~~ - - -:Summary: Markdown link references do not match source. -:Scope: translated strings -:Check class: ``weblate.checks.markup.MarkdownRefLinkCheck`` -:Check identifier: ``md-reflink`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`markdown` -:Flag to enable: ``md-text`` -:Flag to ignore: ``ignore-md-reflink`` - -Markdown link references do not match source. - -.. seealso:: - - `Markdown links `_ - -.. _check-md-syntax: - -Markdown syntax -~~~~~~~~~~~~~~~ - - -:Summary: Markdown syntax does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.markup.MarkdownSyntaxCheck`` -:Check identifier: ``md-syntax`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`markdown` -:Flag to enable: ``md-text`` -:Flag to ignore: ``ignore-md-syntax`` - -Markdown syntax does not match source - -.. seealso:: - - `Markdown inlines `_ - -.. _check-max-length: - -Maximum length of translation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -:Summary: Translation should not exceed given length. -:Scope: translated strings -:Check class: ``weblate.checks.chars.MaxLengthCheck`` -:Check identifier: ``max-length`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``max-length`` -:Flag to ignore: ``ignore-max-length`` - -Checks that translations are of acceptable length to fit available space. -This only checks for the length of translation characters. - -Unlike the other checks, the flag should be set as a ``key:value`` pair like -``max-length:100``. - -.. hint:: - - This check looks at number of chars, what might not be the best metric when - using proportional fonts to render the text. The :ref:`check-max-size` check - does check actual rendering of the text. - - The ``replacements:`` flag might be also useful to expand placeables before - checking the string. - - When ``xml-text`` flag is also used, the length calculation ignores XML tags. - -.. _check-max-size: - -Maximum size of translation -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -:Summary: Translation rendered text should not exceed given size. -:Scope: translated strings -:Check class: ``weblate.checks.render.MaxSizeCheck`` -:Check identifier: ``max-size`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``max-size`` -:Flag to ignore: ``ignore-max-size`` - -Translation rendered text should not exceed given size. It renders the text -with line wrapping and checks if it fits into given boundaries. - -This check needs one or two parameters - maximal width and maximal number of -lines. In case the number of lines is not provided, one line text is -considered. - -You can also configure used font by ``font-*`` directives (see -:ref:`custom-checks`), for example following translation flags say that the -text rendered with ubuntu font size 22 should fit into two lines and 500 -pixels: - -.. code-block:: text - - max-size:500:2, font-family:ubuntu, font-size:22 - -.. hint:: - - You might want to set ``font-*`` directives in :ref:`component` to have the same - font configured for all strings within a component. You can override those - values per string in case you need to customize it per string. - - The ``replacements:`` flag might be also useful to expand placeables before - checking the string. - - When ``xml-text`` flag is also used, the length calculation ignores XML tags. - -.. seealso:: - - * :ref:`fonts` - * :ref:`custom-checks` - * :ref:`check-max-length` - -.. _check-escaped-newline: - -Mismatched \\n -~~~~~~~~~~~~~~ - - -:Summary: Number of \\n literals in translation does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.chars.EscapedNewlineCountingCheck`` -:Check identifier: ``escaped_newline`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-escaped-newline`` - -Usually escaped newlines are important for formatting program output. -Check fails if the number of ``\n`` literals in translation does not match the source. - -.. _check-end-colon: - -Mismatched colon -~~~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both end with a colon. -:Scope: translated strings -:Check class: ``weblate.checks.chars.EndColonCheck`` -:Check identifier: ``end_colon`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-end-colon`` - -Checks that colons are replicated between both source and translation. The -presence of colons is also checked for various languages where they do not -belong (Chinese or Japanese). - -.. seealso:: - - `Colon on Wikipedia `_ - -.. _check-end-ellipsis: - - -Mismatched ellipsis -~~~~~~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both end with an ellipsis. -:Scope: translated strings -:Check class: ``weblate.checks.chars.EndEllipsisCheck`` -:Check identifier: ``end_ellipsis`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-end-ellipsis`` - -Checks that trailing ellipses are replicated between both source and translation. -This only checks for real ellipsis (``…``) not for three dots (``...``). - -An ellipsis is usually rendered nicer than three dots in print, and sounds better with text-to-speech. - -.. seealso:: - - `Ellipsis on Wikipedia `_ - - -.. _check-end-exclamation: - -Mismatched exclamation mark -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both end with an exclamation mark. -:Scope: translated strings -:Check class: ``weblate.checks.chars.EndExclamationCheck`` -:Check identifier: ``end_exclamation`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-end-exclamation`` - -Checks that exclamations are replicated between both source and translation. -The presence of exclamation marks is also checked for various languages where -they do not belong (Chinese, Japanese, Korean, Armenian, Limbu, Myanmar or -Nko). - -.. seealso:: - - `Exclamation mark on Wikipedia `_ - -.. _check-end-stop: - -Mismatched full stop -~~~~~~~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both end with a full stop. -:Scope: translated strings -:Check class: ``weblate.checks.chars.EndStopCheck`` -:Check identifier: ``end_stop`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-end-stop`` - -Checks that full stops are replicated between both source and translation. -The presence of full stops is checked for various languages where they do not belong -(Chinese, Japanese, Devanagari or Urdu). - -.. seealso:: - - `Full stop on Wikipedia `_ - -.. _check-end-interrobang: - -Mismatched interrobang -~~~~~~~~~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both end with an interrobang expression. -:Scope: translated strings -:Check class: ``weblate.checks.chars.EndInterrobangCheck`` -:Check identifier: ``end_interrobang`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-end-interrobang`` - -Checks that interrobang marks are replicated between both source and translation. -It allows the swap between "!?" and "?!". - -.. seealso:: - - `Interrobang mark on Wikipedia `_ - -.. _check-end-question: - -Mismatched question mark -~~~~~~~~~~~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both end with a question mark. -:Scope: translated strings -:Check class: ``weblate.checks.chars.EndQuestionCheck`` -:Check identifier: ``end_question`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-end-question`` - -Checks that question marks are replicated between both source and translation. -The presence of question marks is also checked for various languages where they -do not belong (Armenian, Arabic, Chinese, Korean, Japanese, Ethiopic, Vai or -Coptic). - -.. seealso:: - - `Question mark on Wikipedia `_ - - -.. _check-end-semicolon: - -Mismatched semicolon -~~~~~~~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both end with a semicolon. -:Scope: translated strings -:Check class: ``weblate.checks.chars.EndSemicolonCheck`` -:Check identifier: ``end_semicolon`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-end-semicolon`` - -Checks that semicolons at the end of sentences are replicated between both source and translation. - -.. seealso:: - - `Semicolon on Wikipedia `_ - -.. _check-newline-count: - -Mismatching line breaks -~~~~~~~~~~~~~~~~~~~~~~~ - - -:Summary: Number of new lines in translation does not match source. -:Scope: translated strings -:Check class: ``weblate.checks.chars.NewLineCountCheck`` -:Check identifier: ``newline-count`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-newline-count`` - -Usually newlines are important for formatting program output. -Check fails if the number of new lines in translation does not match the source. - - -.. _check-plurals: - -Missing plurals -~~~~~~~~~~~~~~~ - - -:Summary: Some plural forms are untranslated. -:Scope: translated strings -:Check class: ``weblate.checks.consistency.PluralsCheck`` -:Check identifier: ``plurals`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-plurals`` - -Checks that all plural forms of a source string have been translated. -Specifics on how each plural form is used can be found in the string definition. - -Failing to fill in plural forms will in some cases lead to displaying nothing when -the plural form is in use. - -.. _check-multiple-capital: - -Multiple capitals -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 5.16 - -:Summary: Translation contains words with multiple misplaced capital letters. -:Scope: translated strings -:Check class: ``weblate.checks.chars.MultipleCapitalCheck`` -:Check identifier: ``multiple_capital`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-multiple-capital`` - -Checks for misplaced capitalization by detecting words that contain consecutive -uppercase letters in otherwise lowercase or normally capitalized text (for -example, ``HEllo`` or ``CAmelCase``). Strings that contain capitalization in the -source string are allowed to contain capitalization in the translation. - -.. _check-kabyle-characters: - -Non‑standard characters in Kabyle -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 5.12 - -:Summary: Use standardized Latin Kabyle characters (e.g. ɣ instead of Greek γ; ɛ instead of ε). -:Scope: translated strings -:Check class: ``weblate.checks.chars.KabyleCharactersCheck`` -:Check identifier: ``kabyle-characters`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-kabyle-characters`` - -Checks that Kabyle translations use correct Kabyle letters and not similar -Greek ones, which were often used before Kabyle characters were standardized in -Unicode. - - -.. _check-placeholders: - -Placeholders -~~~~~~~~~~~~ - - -:Summary: Translation is missing some placeholders. -:Scope: translated strings -:Check class: ``weblate.checks.placeholders.PlaceholderCheck`` -:Check identifier: ``placeholders`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``placeholders`` -:Flag to ignore: ``ignore-placeholders`` - -.. versionchanged:: 4.3 - - You can use regular expression as placeholder. - -.. versionchanged:: 4.13 - - With the ``case-insensitive`` flag, the placeholders are not case-sensitive. - -Translation is missing some placeholders. These are either extracted from the -translation file or defined manually using ``placeholders`` flag, more can be -separated with colon, strings with space can be quoted: - -.. code-block:: text - - placeholders:$URL$:$TARGET$:"some long text" - -In case you have some syntax for placeholders, you can use a regular expression: - -.. code-block:: text - - placeholders:r"%[^% ]%" - -You can also have case insensitive placeholders: - -.. code-block:: text - - placeholders:$URL$:$TARGET$,case-insensitive - -.. seealso:: - - :ref:`custom-checks` - -.. _check-prohibited-initial-character: - -Prohibited initial character -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 5.9 - -:Summary: The string starts with a prohibited character in CSV. -:Scope: glossary strings -:Check class: ``weblate.checks.glossary.ProhibitedInitialCharacterCheck`` -:Check identifier: ``prohibited_initial_character`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-prohibited-initial-character`` - -The glossary is often shared as CSV and using some characters at the beginning is -restricted by many applications as these can cause the text being evaluated as -an expression. This also affects :ref:`glossary-mt` where many services use CSV -for synchronizing glossaries and reject such strings. - -.. _check-punctuation-spacing: - -Punctuation spacing -~~~~~~~~~~~~~~~~~~~ - - -:Summary: Missing non breakable space before double punctuation sign. -:Scope: translated strings -:Check class: ``weblate.checks.chars.PunctuationSpacingCheck`` -:Check identifier: ``punctuation_spacing`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-punctuation-spacing`` - -.. versionchanged:: 5.10 - - This check used to apply to Breton language as well, but it was limited to - French only. - -Checks that there is non breakable space before double punctuation sign -(exclamation mark, question mark, semicolon and colon). This rule is used only -in a few selected languages like French, where space before double -punctuation sign is a typographic rule. - -.. seealso:: - - `French and English spacing on Wikipedia `_ - - -.. _check-regex: - -Regular expression -~~~~~~~~~~~~~~~~~~ - - -:Summary: Translation does not match regular expression. -:Scope: translated strings -:Check class: ``weblate.checks.placeholders.RegexCheck`` -:Check identifier: ``regex`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``regex`` -:Flag to ignore: ``ignore-regex`` - -.. versionchanged:: 5.10 - - Extended support for advanced regular expressions including Unicode codepoint properties. - -Translation does not match regular expression. The expression is either extracted from the -translation file or defined manually using ``regex`` flag: - -.. code-block:: text - - regex:^foo|bar$ - -The matching also supports Unicode codepoint properties, including scripts and blocks: - -.. code-block:: text - - regex:^[-_\p{L}\p{N}\p{sc=Deva}\p{sc=Thai}]{1,32}$ - -.. hint:: - - Use :ref:`check-placeholders` for detecting missing placeholders in the string. - -.. seealso:: - - `regex documentation `_ - -.. _check-rst-syntax: - -reStructuredText syntax error -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 5.10 - -:Summary: reStructuredText syntax error in the translation. -:Scope: translated strings -:Check class: ``weblate.checks.markup.RSTSyntaxCheck`` -:Check identifier: ``rst-syntax`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``rst-text`` -:Flag to ignore: ``ignore-rst-syntax`` - -reStructuredText syntax error in the translation. Issues to look for: - -* Mismatched closing/opening tags. -* Missing spaces or interpunction around the reference. The reStructuredText inline blocks need to be separated by non-word characters. -* Using quotes instead of backticks. - -.. seealso:: - - * `reStructuredText Primer`_ - * :ref:`check-rst-references` - -.. _check-reused: - -Reused translation -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 4.18 - -:Summary: Different strings are translated the same. -:Scope: translated strings -:Check class: ``weblate.checks.consistency.ReusedCheck`` -:Check identifier: ``reused`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-reused`` - -Check that fails if the same translation is used on different source strings. -Such translations can be intentional, but can also confuse users. - -.. _check-same-plurals: - -Same plurals -~~~~~~~~~~~~ - - -:Summary: Some plural forms are translated in the same way. -:Scope: translated strings -:Check class: ``weblate.checks.consistency.SamePluralsCheck`` -:Check identifier: ``same-plurals`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-same-plurals`` - -Check that fails if some plural forms are duplicated in the translation. -In most languages they have to be different. - -.. _check-begin-newline: - -Starting newline -~~~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both start with a newline. -:Scope: translated strings -:Check class: ``weblate.checks.chars.BeginNewlineCheck`` -:Check identifier: ``begin_newline`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-begin-newline`` - -Newlines usually appear in source strings for good reason, omissions or additions -can lead to formatting problems when the translated text is put to use. - -.. seealso:: - - :ref:`check-end-newline` - -.. _check-begin-space: - -Starting spaces -~~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both start with same number of spaces. -:Scope: translated strings -:Check class: ``weblate.checks.chars.BeginSpaceCheck`` -:Check identifier: ``begin_space`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-begin-space`` - -A space in the beginning of a string is usually used for indentation in the interface and thus -important to keep. - -.. _check-end-newline: - -Trailing newline -~~~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both end with a newline. -:Scope: translated strings -:Check class: ``weblate.checks.chars.EndNewlineCheck`` -:Check identifier: ``end_newline`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-end-newline`` - -Newlines usually appear in source strings for good reason, omissions or additions -can lead to formatting problems when the translated text is put to use. - -.. seealso:: - - :ref:`check-begin-newline` - -.. _check-end-space: - -Trailing space -~~~~~~~~~~~~~~ - - -:Summary: Source and translation do not both end with a space. -:Scope: translated strings -:Check class: ``weblate.checks.chars.EndSpaceCheck`` -:Check identifier: ``end_space`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-end-space`` - -Checks that trailing spaces are replicated between both source and translation. - -Trailing space is usually utilized to space out neighbouring elements, so -removing it might break layout. - -.. _check-same: - -Unchanged translation -~~~~~~~~~~~~~~~~~~~~~ - - -:Summary: Source and translation are identical. -:Scope: translated strings -:Check class: ``weblate.checks.same.SameCheck`` -:Check identifier: ``same`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-same`` - -Happens if the source and corresponding translation strings are identical, down -to at least one of the plural forms. Some strings commonly found across all -languages are ignored, and various markups are stripped. This reduces the -number of false positives. - -This check can help find strings mistakenly untranslated. - -The default behavior of this check is to exclude words from the built-in terms -list from the checking. These are words which are frequently not being -translated. This is useful to avoid false positives on short strings, which -consist only of a single word which is the same in several languages. This list -can be disabled by adding ``strict-same`` flag to a string or component. - -.. versionchanged:: 4.17 - - With ``check-glossary`` flag (see :ref:`check-check-glossary`), the - untranslatable glossary terms are excluded from the checking. - -.. seealso:: - - * :ref:`check-check-glossary` - * :ref:`component` - * :ref:`custom-checks` - -.. _check-safe-html: - -Unsafe HTML -~~~~~~~~~~~ - - -:Summary: The translation uses unsafe HTML markup. -:Scope: translated strings -:Check class: ``weblate.checks.markup.SafeHTMLCheck`` -:Check identifier: ``safe-html`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`html`, :ref:`markdown` -:Flag to enable: ``safe-html`` -:Flag to ignore: ``ignore-safe-html`` - -The translation uses unsafe HTML markup. This check has to be enabled using -``safe-html`` flag (see :ref:`custom-checks`). There is also accompanied -autofixer which can automatically sanitize the markup. - -.. hint:: - - When ``md-text`` flag is also used, the Markdown style links are also allowed. - -.. seealso:: - - The HTML check is performed by the `Ammonia `_ - library. - - - -.. _check-url: - -URL -~~~ - - -:Summary: The translation does not contain an URL. -:Scope: translated strings -:Check class: ``weblate.checks.markup.URLCheck`` -:Check identifier: ``url`` -:Trigger: This check needs to be enabled using a flag. -:Flag to enable: ``url`` -:Flag to ignore: ``ignore-url`` - -The translation does not contain an URL. This is triggered only in case the -unit is marked as containing URL. In that case the translation has to be a -valid URL. - -.. _check-xml-tags: - -XML markup -~~~~~~~~~~ - - -:Summary: XML tags in translation do not match source. -:Scope: translated strings -:Check class: ``weblate.checks.markup.XMLTagsCheck`` -:Check identifier: ``xml-tags`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-xml-tags`` - -This usually means the resulting output will look different. In most cases this is -not a desired result from changing the translation, but occasionally it is. - -Checks that XML tags are replicated between both source and translation. - -The check is automatically enabled for XML like strings. You might need to add -``xml-text`` flag in some cases to force turning it on. - -.. note:: - - This check is disabled by the ``safe-html`` flag as the HTML cleanup done by - it can produce HTML markup which is not valid XML. - -.. _check-xml-chars-around-tags: - -XML surrounding characters -~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -:Summary: Characters surrounding XML tags in translation do not align with source. -:Scope: translated strings -:Check class: ``weblate.checks.markup.XMLCharsAroundTagsCheck`` -:Check identifier: ``xml-chars-around-tags`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-xml-chars-around-tags`` - -Checks that the characters surrounding an XML tag are consistent between both -source and translation. Ensures letters are not replaced with non-letters, and vice versa. - -.. note:: - - This check is disabled by the ``safe-html`` flag as the HTML cleanup done by - it can produce HTML markup which is not valid XML. - -.. _check-xml-invalid: - - -XML syntax -~~~~~~~~~~ - - -:Summary: The translation is not valid XML. -:Scope: translated strings -:Check class: ``weblate.checks.markup.XMLValidityCheck`` -:Check identifier: ``xml-invalid`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-xml-invalid`` - -The XML markup is not valid. - -The check is automatically enabled for XML like strings. You might need to add -``xml-text`` flag in some cases to force turning it on. - -.. note:: - - This check is disabled by the ``safe-html`` flag as the HTML cleanup done by - it can produce HTML markup which is not valid XML. - -.. _check-zero-width-space: - -Zero-width space -~~~~~~~~~~~~~~~~ - - -:Summary: Translation contains extra zero-width space character. -:Scope: translated strings -:Check class: ``weblate.checks.chars.ZeroWidthSpaceCheck`` -:Check identifier: ``zero-width-space`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-zero-width-space`` - -Zero-width space () characters are used to break messages within words (word wrapping). - -As they are usually inserted by mistake, this check is triggered once they are present -in translation. Some programs might have problems when this character is used. - -.. seealso:: - - `Zero width space on Wikipedia `_ - - - -Source checks -------------- - -Source checks can help developers improve the quality of source strings. - -.. _check-ellipsis: - -Ellipsis -~~~~~~~~ - - -:Summary: The string uses three dots (``...``) instead of an ellipsis character (``…``). -:Scope: source strings -:Check class: ``weblate.checks.source.EllipsisCheck`` -:Check identifier: ``ellipsis`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-ellipsis`` - -This fails when the string uses three dots (``...``) when it should use an ellipsis character (``…``). - -Using the Unicode character is in most cases the better approach and looks better -rendered, and may sound better with text-to-speech. - -.. seealso:: - - `Ellipsis on Wikipedia `_ - -.. _check-fluent-source-inner-html: - -Fluent source inner HTML -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 5.0 - -:Summary: Fluent source should be valid inner HTML. -:Scope: source strings -:Check class: ``weblate.checks.fluent.inner_html.FluentSourceInnerHTMLCheck`` -:Check identifier: ``fluent-source-inner-html`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`fluent` -:Flag to enable: ``fluent-source-inner-html`` -:Flag to ignore: ``ignore-fluent-source-inner-html`` - -Fluent is often used in contexts where the value for a Message (or Term) is -meant to be used directly as ``.innerHTML`` (rather than ``.textContent``) for -some HTML element. For example, when using the Fluent DOM package. - -The aim of this check is to predict how the value will be parsed as inner HTML, -assuming a HTML5 conforming parser, to catch cases where there would be some -"unintended" loss of the string, without being too strict about technical -parsing errors that do *not* lead to a loss of the string. - -This check is applied to the value of Fluent Messages or Terms, but not their -Attributes. For Messages, the Fluent Attributes are often just HTML attribute -values, so can be arbitrary strings. For Terms, the Fluent Attributes are -often language properties that can only be referenced in the selectors of Fluent -Select Expressions. - -Generally, most Fluent values are not expected to contain any HTML markup. -Therefore, this check does not expect or want translators and developers to have -to care about strictly avoiding *any* technical HTML5 parsing errors (let alone -XHTML parsing errors). Instead, this check will just want to warn them when they -may have unintentionally opened a HTML tag or inserted a character reference. - -Moreover, for the Fluent values that intentionally contain HTML tags or -character references, this check will verify some "good practices", such as -matching closing and ending tags, valid character references, and quoted -attribute values. In addition, whilst the HTML5 specification technically allows -for quite arbitrary tag and attribute names, this check will restrain them to -some basic ASCII values that should cover the standard HTML5 element tags and -attributes, as well as allow *some* custom element or attribute names. This is -partially to ensure that the user is using HTML intentionally. - -Examples: - -.. list-table:: Fluent inner HTML examples - :header-rows: 1 - - * - Value - - Warns? - - Reason - - * - ``three`` - - yes - - Missing a closing tag. - - * - ``three `` - - yes - - ``four`` is not a HTML void element, so should not self-close. - - * - ``text`` - - no - - Custom element tag with a matching closing tag. - - * - ``a b`` - - no - - ``img`` is a HTML void element. Self-closing is allowed. - - * - ``a
b`` - - no - - ``br`` is a HTML void element. - - * - ```` - - yes - - The attribute value is not quoted. - - * - ```` - - yes - - Non-ASCII tag name. - - * - ``kindðical`` - - yes - - The ``ð`` part would be converted to ``ð``. - - * - ``kindðical`` - - no - - The character reference seems to be intentional. - - * - ``three<e;four`` - - yes - - The ``<e;`` part would be converted to ```_ - -.. _check-fluent-source-syntax: - -Fluent source syntax -~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 5.0 - -:Summary: Fluent syntax error in the source. -:Scope: source strings -:Check class: ``weblate.checks.fluent.syntax.FluentSourceSyntaxCheck`` -:Check identifier: ``fluent-source-syntax`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`fluent` -:Flag to enable: ``fluent-source-syntax`` -:Flag to ignore: ``ignore-fluent-source-syntax`` - -In Weblate, Fluent strings use Fluent syntax for references and variables, but -also for more complex features like defining attributes and selector variants, -including plurals. This check ensures that the syntax used in source will be -valid for Fluent. - -.. seealso:: - - * :ref:`check-fluent-target-syntax` - * `Fluent Syntax Guide `_ - * `Mozilla Basic Syntax Guide `_ - -.. _check-icu-message-format-syntax: - -ICU MessageFormat syntax -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 4.9 - -:Summary: Syntax errors in ICU MessageFormat strings. -:Scope: source strings -:Check class: ``weblate.checks.icu.ICUSourceCheck`` -:Check identifier: ``icu_message_format_syntax`` -:Trigger: This check needs to be enabled using a flag. -:File formats automatically enabling this check: :ref:`arb`, :ref:`formatjs` -:Flag to enable: ``icu-message-format`` -:Flag to ignore: ``ignore-icu-message-format`` - -.. seealso:: - - :ref:`check-icu-message-format` - -.. _check-long-untranslated: - -Long untranslated -~~~~~~~~~~~~~~~~~ - -.. versionadded:: 4.1 - -:Summary: The string has not been translated for a long time. -:Scope: source strings -:Check class: ``weblate.checks.source.LongUntranslatedCheck`` -:Check identifier: ``long_untranslated`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-long-untranslated`` - -When the string has not been translated for a long time, it can indicate a problem in a -source string making it hard to translate. - - -.. _check-multiple-failures: - -Multiple failing checks -~~~~~~~~~~~~~~~~~~~~~~~ - - -:Summary: The translations in several languages have failing checks. -:Scope: source strings -:Check class: ``weblate.checks.source.MultipleFailingCheck`` -:Check identifier: ``multiple_failures`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-multiple-failures`` - -Numerous translations of this string have failing quality checks. This is -usually an indication that something could be done to improve the source -string. - -This check failing can quite often be caused by a missing full stop at the end of -a sentence, or similar minor issues which translators tend to fix in -translation, while it would be better to fix it in the source string. - -.. _check-unnamed-format: - -Multiple unnamed variables -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 4.1 - -:Summary: There are multiple unnamed variables in the string, making it impossible for translators to reorder them. -:Scope: source strings -:Check class: ``weblate.checks.format.MultipleUnnamedFormatsCheck`` -:Check identifier: ``unnamed_format`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-unnamed-format`` - -There are multiple unnamed variables in the string, making it impossible for -translators to reorder them. - -Consider using named variables instead to allow translators to reorder them. - -.. _check-optional-plural: - -Unpluralised -~~~~~~~~~~~~ - - -:Summary: The string is used as plural, but not using plural forms. -:Scope: source strings -:Check class: ``weblate.checks.source.OptionalPluralCheck`` -:Check identifier: ``optional_plural`` -:Trigger: This check is always enabled but can be ignored using a flag. -:Flag to ignore: ``ignore-optional-plural`` - -The string is used as a plural, but does not use plural forms. In case your -translation system supports this, you should use the plural aware variant of -it. - -For example with Gettext in Python it could be: - -.. code-block:: python - - from gettext import ngettext - - print(ngettext("Selected %d file", "Selected %d files", files) % files) - - -.. _placeables-mt: - -Placeables in automatic suggestion ----------------------------------- - -Checks for placeables expose information on current placeables and this can be -used to instruct automatic suggestion engines to keep them. The support for -this varies in different services and in many cases there is no way to enforce -keeping placeables intact. - -.. seealso:: - - :doc:`/admin/machine` - -.. _reStructuredText Primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +.. include:: /snippets/checks-autogenerated.rst diff --git a/weblate/addons/base.py b/weblate/addons/base.py index e180b8e61390..470b30c2da5d 100644 --- a/weblate/addons/base.py +++ b/weblate/addons/base.py @@ -22,6 +22,7 @@ from weblate.trans.templatetags.translations import format_json from weblate.trans.util import get_clean_env from weblate.utils import messages +from weblate.utils.docs import DocVersionsMixin from weblate.utils.errors import report_error from weblate.utils.files import cleanup_error_message from weblate.utils.html import format_html_join_comma, list_to_tuples @@ -46,7 +47,7 @@ class CompatDict(TypedDict, total=False): edit_template: set[bool] -class BaseAddon: +class BaseAddon(DocVersionsMixin): """Base class for Weblate add-ons.""" events: ClassVar[set[AddonEvent]] = set() diff --git a/weblate/addons/cdn.py b/weblate/addons/cdn.py index 7f062f5da4d9..c8463a1709d0 100644 --- a/weblate/addons/cdn.py +++ b/weblate/addons/cdn.py @@ -34,6 +34,7 @@ class CDNJSAddon(BaseAddon): AddonEvent.EVENT_POST_UPDATE, } name = "weblate.cdn.cdnjs" + version_added = "4.2" verbose = gettext_lazy("JavaScript localization CDN") description = gettext_lazy( "Publishes translations into content delivery network " diff --git a/weblate/addons/cleanup.py b/weblate/addons/cleanup.py index 0234d3396910..3a3f46708549 100644 --- a/weblate/addons/cleanup.py +++ b/weblate/addons/cleanup.py @@ -96,6 +96,7 @@ class RemoveBlankAddon(BaseCleanupAddon): AddonEvent.EVENT_POST_UPDATE, } icon = "eraser.svg" + version_added = "4.4" def update_translations(self, component: Component, previous_head: str) -> None: for translation in self.iterate_translations(component): diff --git a/weblate/addons/events.py b/weblate/addons/events.py index 0c9cb6b76cd0..cdcf842cd5f2 100644 --- a/weblate/addons/events.py +++ b/weblate/addons/events.py @@ -1,6 +1,7 @@ # Copyright © Michal Čihař # # SPDX-License-Identifier: GPL-3.0-or-later +from __future__ import annotations from django.db.models import IntegerChoices @@ -22,6 +23,29 @@ class AddonEvent(IntegerChoices): EVENT_UNIT_POST_SYNC = 14, "Unit post-sync" EVENT_INSTALL = 15, "Add-on installation" + @classmethod + def descriptions(cls) -> dict[AddonEvent, str]: + return { + cls.EVENT_POST_PUSH: "Triggered just after the repository is pushed upstream.", + cls.EVENT_POST_UPDATE: "Triggered whenever new changes are pulled from the upstream repository.", + cls.EVENT_PRE_COMMIT: "Triggered just before the changes are committed.", + cls.EVENT_POST_COMMIT: "Triggered just after the changes are committed.", + cls.EVENT_POST_ADD: "Triggered just after the new translation is added and committed.", + cls.EVENT_UNIT_PRE_CREATE: "Triggered just after the newly created string is saved.", + cls.EVENT_UNIT_POST_SAVE: "Triggered just after the string is saved.", + cls.EVENT_PRE_UPDATE: "Triggered just before the repository update is attempted.", + cls.EVENT_PRE_PUSH: "Triggered just before the repository is pushed upstream.", + cls.EVENT_DAILY: "Triggered daily, but add-ons usually split the daily load between components depending on :setting:`BACKGROUND_TASKS`.", + cls.EVENT_COMPONENT_UPDATE: """Triggered whenever a change happens in a component such as: + +* Strings are changed in the repository. +* A string is added. +* A new translation is added.""", + cls.EVENT_CHANGE: "Triggered after a Change event is created.", + cls.EVENT_UNIT_POST_SYNC: "Triggered after the string is synchronized with the VCS.", + cls.EVENT_INSTALL: "Triggered when add-on is being installed.", + } + POST_CONFIGURE_EVENTS = { AddonEvent.EVENT_POST_COMMIT, diff --git a/weblate/addons/fedora_messaging.py b/weblate/addons/fedora_messaging.py index 4df43047429b..2c8e9986e762 100644 --- a/weblate/addons/fedora_messaging.py +++ b/weblate/addons/fedora_messaging.py @@ -34,6 +34,7 @@ class FedoraMessagingAddon(ChangeBaseAddon): "Sends notifications to a Fedora Messaging compatible AMQP exchange." ) multiple = False + version_added = "5.15" @classmethod def can_install( diff --git a/weblate/addons/generate.py b/weblate/addons/generate.py index bbf6093dece5..a6c102f88b7b 100644 --- a/weblate/addons/generate.py +++ b/weblate/addons/generate.py @@ -172,6 +172,7 @@ class PseudolocaleAddon(LocaleGenerateAddonBase): settings_form = PseudolocaleAddonForm user_name = "pseudolocale" user_verbose = "Pseudolocale add-on" + version_added = "4.5" def daily(self, component: Component, activity_log_id: int | None = None) -> None: # Check all strings @@ -252,6 +253,7 @@ class PrefillAddon(LocaleGenerateAddonBase): description = gettext_lazy("Fills in translation strings with source string.") user_name = "prefill" user_verbose = "Prefill add-on" + version_added = "4.11" def daily(self, component: Component, activity_log_id: int | None = None) -> None: # Check all strings @@ -288,6 +290,7 @@ class FillReadOnlyAddon(LocaleGenerateAddonBase): ) user_name = "fill" user_verbose = "Fill read-only add-on" + version_added = "4.18" def daily(self, component: Component, activity_log_id: int | None = None) -> None: self.do_update(component) diff --git a/weblate/addons/gettext.py b/weblate/addons/gettext.py index 9c39930b832a..4ba51237ff50 100644 --- a/weblate/addons/gettext.py +++ b/weblate/addons/gettext.py @@ -266,6 +266,12 @@ class MsgmergeAddon(GettextBaseAddon, UpdateBaseAddon): ) alert = "MsgmergeAddonError" compat: ClassVar[CompatDict] = {"file_format": {"po"}} + versions_changed = ( + ( + "5.13", + ":guilabel:`Settings` configuration has been moved to :ref:`file_format_params`.", + ), + ) @classmethod def can_install( diff --git a/weblate/addons/management/commands/list_addons.py b/weblate/addons/management/commands/list_addons.py index c0a02abc4676..74f1620b42b5 100644 --- a/weblate/addons/management/commands/list_addons.py +++ b/weblate/addons/management/commands/list_addons.py @@ -4,13 +4,15 @@ from __future__ import annotations +import operator from textwrap import wrap from typing import TYPE_CHECKING from weblate.addons.events import POST_CONFIGURE_EVENTS, AddonEvent from weblate.addons.models import ADDONS, Addon +from weblate.machinery.models import MACHINERY from weblate.trans.models import Component, Project -from weblate.utils.management.base import BaseCommand +from weblate.utils.management.base import DocGeneratorCommand from weblate.utils.rst import format_rst_string, format_table if TYPE_CHECKING: @@ -18,10 +20,15 @@ from weblate.utils.rst import CellType + SKIP_FIELDS: tuple[tuple[str, str]] = ( ("weblate.flags.bulk", "path"), # Used internally only ) +EXTRA_ANCHOR_ALIASES = { + "weblate.fedora_messaging.publish": "fedora-messaging", +} + def event_link(event: AddonEvent) -> str: return f"addon-event-{event.label.lower().replace(' ', '-')}" @@ -34,75 +41,64 @@ def sorted_events(events: Iterable[AddonEvent]) -> Iterable[AddonEvent]: SHARED_PARAMS = {"engines", "file_format", "events"} -class Command(BaseCommand): +class Command(DocGeneratorCommand): help = "List installed add-ons" - def get_help_text(self, field, name: str) -> str: - result = [] - if field.help_text: - result.append(format_rst_string(field.help_text)) - choices = getattr(field, "choices", None) - if choices: - if name in SHARED_PARAMS: - # Add link to shared docs - result.append(f":ref:`addon-choice-{name}`") - elif name not in { - "component", - "source", - "target", - }: - # List actual choices - if result: - result.append("") - result.extend(self.get_choices_table(choices)) - return "\n".join(result) - - def get_choices_table(self, choices: list[tuple[str, str]]) -> list[str]: - result = [ - ".. list-table:: Available choices:", - " :width: 100%", - "", - ] - for value, description in choices: - if not value and not description: - continue - result.extend( - ( - f" * - ``{value}``".replace("\\", "\\\\"), - f" - {format_rst_string(description)}".replace("\\", "\\\\"), - ) - ) - return result - def handle(self, *args, **options) -> None: """List installed add-ons.""" - self.stdout.write(""".. - Partly generated using ./manage.py list_addons -""") - # Events - self.stdout.write(".. _addon-event-install:\n\n") - self.stdout.write("Add-on installation\n") - self.stdout.write("-------------------\n\n") + # Shared parameters + self.params = SHARED_PARAMS.copy() + self.param_docs: dict[str, list[str]] = {} + + self.generate_events_doc() + self.generate_addons_doc() + self.generate_addon_parameters_doc() + + self.write_sections(options.get("output")) + + def generate_events_doc(self) -> None: + content = [] + content.extend( + [ + "Events that trigger add-ons", + "+++++++++++++++++++++++++++", + ] + ) + event_descriptions = AddonEvent.descriptions() for event in sorted_events(AddonEvent): - self.stdout.write(f".. _{event_link(event)}:\n\n") - self.stdout.write(f"{event.label}\n") - self.stdout.write("-" * len(event.label)) - self.stdout.write("\n\n") - self.stdout.write("\n\n") + content.extend( + ( + f".. _{event_link(event)}:\n", + f"{event.label}", + "-" * len(event.label) + "\n", + ) + ) + if description := event_descriptions.get(event): + content.append(description) + content.append("") + self.add_section("events", content) - # Shared parameters - params = SHARED_PARAMS.copy() - param_docs: dict[str, list[str]] = {} + def generate_addons_doc(self) -> None: + self.add_section( + "addons-header", + ["Built-in add-ons", "++++++++++++++++"], + ) - # Actual add-ons fake_addon = Addon(component=Component(project=Project(pk=-1), pk=-1)) for addon_name, obj in sorted(ADDONS.items()): - self.stdout.write(f".. _addon-{obj.name}:") - self.stdout.write("\n") - self.stdout.write(str(obj.verbose)) - self.stdout.write("-" * len(obj.verbose)) - self.stdout.write("\n") - self.stdout.write(f":Add-on ID: ``{obj.name}``") + addon_lines = [] + if obj.name in EXTRA_ANCHOR_ALIASES: + addon_lines.append(f".. _{EXTRA_ANCHOR_ALIASES[obj.name]}:") + addon_lines.extend( + ( + f".. _addon-{obj.name}:", + "", + str(obj.verbose), + "-" * len(obj.verbose), + ) + ) + addon_lines.extend([*obj.get_versions_rst_lines(), ""]) + addon_lines.append(f":Add-on ID: ``{obj.name}``") prefix = ":Configuration: " if obj.settings_form: form = obj(fake_addon).get_settings_form(None) # type: ignore[operator] @@ -117,33 +113,90 @@ def handle(self, *args, **options) -> None: ] for table_row in format_table(table, None): - self.stdout.write(f"{prefix}{table_row}") + table_row = table_row.strip( + "\n" + ) # self.write_sections() inserts newlines + addon_lines.append(f"{prefix}{table_row}") if not prefix.isspace(): prefix = " " * len(prefix) + addon_lines.append("") - for name in params & set(form.fields): + for name in self.params & set(form.fields): field = form.fields[name] - params.remove(name) - param_docs[name] = [ + choices = list(field.choices) + if name == "engines": + choices.extend( + [ + (machine_name, machine_class.name) + for machine_name, machine_class in MACHINERY.items() + ] + ) + choices = sorted(set(choices), key=operator.itemgetter(1)) + self.params.remove(name) + self.param_docs[name] = [ f".. _addon-choice-{name}:", "", f"{field.label}", "-" * len(field.label), "", - *self.get_choices_table(field.choices), + *self.get_choices_table(choices), + "", ] else: - self.stdout.write(f"{prefix}`This add-on has no configuration.`") + addon_lines.append(f"{prefix}`This add-on has no configuration.`") events = ", ".join( f":ref:`{event_link(event)}`" for event in sorted_events(obj.events) ) if POST_CONFIGURE_EVENTS & set(obj.events): events = f":ref:`addon-event-add-on-installation`, {events}" - self.stdout.write(f":Triggers: {events}") - self.stdout.write("\n") - self.stdout.write("\n".join(wrap(str(obj.description), 79))) - self.stdout.write("\n") - - for _name, lines in sorted(param_docs.items()): - self.stdout.write("\n".join(lines)) - self.stdout.write("\n") + addon_lines.extend( + [ + f":Triggers: {events}", + "", + "\n".join(wrap(str(obj.description), 79)), + ] + ) + self.add_section(addon_name, addon_lines) + + def generate_addon_parameters_doc(self) -> None: + self.add_section( + "addon-parameters", + ["\n".join(items) for items in self.param_docs.values()], + ) + + def get_help_text(self, field, name: str) -> str: + result = [] + if field.help_text: + result.append(format_rst_string(field.help_text)) + choices = getattr(field, "choices", None) + if choices: + if name in SHARED_PARAMS: + # Add link to shared docs + result.append(f":ref:`addon-choice-{name}`") + elif name not in { + "component", + "source", + "target", + }: + # List actual choices + if result: + result.append("") + result.extend(self.get_choices_table(choices)) + return "\n".join(result) + + def get_choices_table(self, choices: list[tuple[str, str]]) -> list[str]: + result = [ + ".. list-table:: Available choices:", + " :width: 100%", + "", + ] + for value, description in choices: + if not value and not description: + continue + result.extend( + ( + f" * - ``{value}``".replace("\\", "\\\\"), + f" - {format_rst_string(description)}".replace("\\", "\\\\"), + ) + ) + return result diff --git a/weblate/addons/tests.py b/weblate/addons/tests.py index 92a1ab2d2f67..4ce51b1d4441 100644 --- a/weblate/addons/tests.py +++ b/weblate/addons/tests.py @@ -2204,3 +2204,13 @@ def test_form(self) -> None: follow=True, ) self.assertContains(response, "Installed 1 add-on") + + +class TestCommand(ViewTestCase): + def test_list_addons(self) -> None: + output = StringIO() + call_command("list_addons", stdout=output) + self.assertIn(".. _addon-event-add-on-installation:", output.getvalue()) + + with self.assertRaises(FileNotFoundError): + call_command("list_addons", "-o", "missing_fileXXX.rst", stdout=StringIO()) diff --git a/weblate/addons/webhooks.py b/weblate/addons/webhooks.py index 46786701762f..fc06d9d665b3 100644 --- a/weblate/addons/webhooks.py +++ b/weblate/addons/webhooks.py @@ -114,6 +114,13 @@ class WebhookAddon(JSONWebhookBaseAddon): description = gettext_lazy( "Sends notifications to external services based on selected events, following the Standard Webhooks specification." ) + version_added = "5.11" + versions_changed = ( + ( + "5.15", + "Compliance of the secret length with the specification is now validated.", + ), + ) settings_form = WebhooksAddonForm @@ -200,6 +207,7 @@ class SlackWebhookAddon(JSONWebhookBaseAddon): ) icon = "slack.svg" settings_form = BaseWebhooksAddonForm + version_added = "5.12" def build_webhook_payload(self, change: Change) -> PayloadType: message_header = "" diff --git a/weblate/checks/base.py b/weblate/checks/base.py index 6571b0ac4e1a..116176a5c1bf 100644 --- a/weblate/checks/base.py +++ b/weblate/checks/base.py @@ -16,7 +16,7 @@ from siphashc import siphash from weblate.utils.classloader import ClassLoaderProtocol -from weblate.utils.docs import get_doc_url +from weblate.utils.docs import DocVersionsMixin, get_doc_url from weblate.utils.html import format_html_join_comma from weblate.utils.xml import parse_xml @@ -42,7 +42,7 @@ class MissingExtraDict(TypedDict, total=False): errors: list[str] -class BaseCheck(ClassLoaderProtocol): +class BaseCheck(ClassLoaderProtocol, DocVersionsMixin): """Basic class for checks.""" check_id = "" diff --git a/weblate/checks/chars.py b/weblate/checks/chars.py index 9e9c298b2fce..1a2c02f2d2bd 100644 --- a/weblate/checks/chars.py +++ b/weblate/checks/chars.py @@ -109,6 +109,7 @@ class KabyleCharactersCheck(TargetCheck): description = gettext_lazy( "Use standardized Latin Kabyle characters (e.g. ɣ instead of Greek γ; ɛ instead of ε)." ) + version_added = "5.12" confusable_to_standard: ClassVar[dict[str, str]] = { "\u03b3": "\u0263", @@ -516,6 +517,12 @@ class PunctuationSpacingCheck(TargetCheck): description = gettext_lazy( "Missing non breakable space before double punctuation sign." ) + versions_changed = ( + ( + "5.10", + "This check used to apply to Breton language as well, but it was limited to French only.", + ), + ) def should_skip(self, unit: Unit) -> bool: if ( @@ -590,6 +597,7 @@ class MultipleCapitalCheck(TargetCheck): description = gettext_lazy( "Translation contains words with multiple misplaced capital letters." ) + version_added = "5.16" # matches sequences of 2+ uppercase letters in *any language* UPPERCASE_SEQ = regex.compile(r"\p{Lu}{2,}") diff --git a/weblate/checks/consistency.py b/weblate/checks/consistency.py index a93fde17ce39..090bf3a20882 100644 --- a/weblate/checks/consistency.py +++ b/weblate/checks/consistency.py @@ -162,6 +162,7 @@ class ReusedCheck(TargetCheck, BatchCheckMixin): propagates = "target" batch_project_wide = True skip_suggestions = True + version_added = "4.18" def should_skip(self, unit: Unit): if unit.translation.plural.number <= 1 or not any(unit.get_target_plurals()): diff --git a/weblate/checks/duplicate.py b/weblate/checks/duplicate.py index bf761e2aba1f..d4310a01d405 100644 --- a/weblate/checks/duplicate.py +++ b/weblate/checks/duplicate.py @@ -38,6 +38,7 @@ class DuplicateCheck(TargetCheck): check_id = "duplicate" name = gettext_lazy("Consecutive duplicated words") description = gettext_lazy("Text contains the same word twice in a row.") + version_added = "4.1" def should_skip(self, unit: Unit) -> bool: # Ignore the check for Toki Pona which often uses repeating words diff --git a/weblate/checks/fluent/inner_html.py b/weblate/checks/fluent/inner_html.py index e2e31182bb9b..f0f0769c4b53 100644 --- a/weblate/checks/fluent/inner_html.py +++ b/weblate/checks/fluent/inner_html.py @@ -950,6 +950,7 @@ class FluentSourceInnerHTMLCheck(_FluentInnerHTMLCheck, SourceCheck): name = gettext_lazy("Fluent source inner HTML") description = gettext_lazy("Fluent source should be valid inner HTML.") default_disabled = True + version_added = "5.0" def check_source_unit(self, sources: list[str], unit: TransUnitModel) -> bool: try: @@ -1228,6 +1229,7 @@ class FluentTargetInnerHTMLCheck(_FluentInnerHTMLCheck, TargetCheck): name = gettext_lazy("Fluent translation inner HTML") description = gettext_lazy("Fluent target should be valid inner HTML that matches.") default_disabled = True + version_added = "5.0" @classmethod def _compare_inner_html( diff --git a/weblate/checks/fluent/parts.py b/weblate/checks/fluent/parts.py index a68b2b8c8608..74ad2864144e 100644 --- a/weblate/checks/fluent/parts.py +++ b/weblate/checks/fluent/parts.py @@ -112,6 +112,7 @@ class FluentPartsCheck(TargetCheck): name = gettext_lazy("Fluent parts") description = gettext_lazy("Fluent parts should match.") default_disabled = True + version_added = "5.0" @classmethod def _compare_parts( diff --git a/weblate/checks/fluent/references.py b/weblate/checks/fluent/references.py index 56feb1cc5659..f30ad7666d12 100644 --- a/weblate/checks/fluent/references.py +++ b/weblate/checks/fluent/references.py @@ -673,6 +673,7 @@ class FluentReferencesCheck(TargetCheck): name = gettext_lazy("Fluent references") description = gettext_lazy("Fluent references should match.") default_disabled = True + version_added = "5.0" @classmethod def _compare_references( diff --git a/weblate/checks/fluent/syntax.py b/weblate/checks/fluent/syntax.py index 4ef15bc9575e..92c6c91d6ff2 100644 --- a/weblate/checks/fluent/syntax.py +++ b/weblate/checks/fluent/syntax.py @@ -46,6 +46,7 @@ class FluentSourceSyntaxCheck(_FluentSyntaxCheck, SourceCheck): name = gettext_lazy("Fluent source syntax") description = gettext_lazy("Fluent syntax error in the source.") default_disabled = True + version_added = "5.0" def check_source_unit(self, sources: list[str], unit: TransUnitModel) -> bool: return self.check_fluent_syntax(sources[0], unit) @@ -63,6 +64,7 @@ class FluentTargetSyntaxCheck(_FluentSyntaxCheck, TargetCheck): name = gettext_lazy("Fluent translation syntax") description = gettext_lazy("Fluent syntax error in the translation.") default_disabled = True + version_added = "5.0" def check_single( self, diff --git a/weblate/checks/format.py b/weblate/checks/format.py index d731780003e6..00c4f19a7148 100644 --- a/weblate/checks/format.py +++ b/weblate/checks/format.py @@ -803,6 +803,7 @@ class I18NextInterpolationCheck(BaseFormatCheck): regexp = I18NEXT_MATCH # https://www.i18next.com/translation-function/plurals plural_parameter_regexp = re.compile(r"{{count}}") + version_added = "4.0" def cleanup_string(self, text): return WHITESPACE.sub("", text) @@ -830,6 +831,7 @@ class PercentPlaceholdersCheck(BaseFormatCheck): description = gettext_lazy("The percent placeholders do not match source.") regexp = PERCENT_MATCH plural_parameter_regexp = re.compile(r"%(?:count|number|num|n)%") + version_added = "4.0" class VueFormattingCheck(BaseFormatCheck): @@ -868,6 +870,7 @@ class MultipleUnnamedFormatsCheck(SourceCheck): "There are multiple unnamed variables in the string, " "making it impossible for translators to reorder them." ) + version_added = "4.1" def check_source_unit(self, sources: list[str], unit: Unit) -> bool: """Check source string.""" diff --git a/weblate/checks/glossary.py b/weblate/checks/glossary.py index b0691f1d6f6c..e0ea31aabb75 100644 --- a/weblate/checks/glossary.py +++ b/weblate/checks/glossary.py @@ -28,6 +28,7 @@ class GlossaryCheck(TargetCheck): description = gettext_lazy( "The translation does not follow terms defined in a glossary." ) + version_added = "4.5" def check_single(self, source: str, target: str, unit: Unit): from weblate.glossary.models import get_glossary_terms @@ -95,6 +96,7 @@ class ProhibitedInitialCharacterCheck(TargetCheck): # Process readonly (source) strings ignore_readonly = False glossary = True + version_added = "5.9" def should_skip(self, unit: Unit) -> bool: if not unit.translation.component.is_glossary: diff --git a/weblate/checks/icu.py b/weblate/checks/icu.py index 15c2a1780144..2cb305f546a8 100644 --- a/weblate/checks/icu.py +++ b/weblate/checks/icu.py @@ -260,6 +260,7 @@ class ICUSourceCheck(ICUCheckMixin, SourceCheck): name = gettext_lazy("ICU MessageFormat syntax") description = gettext_lazy("Syntax errors in ICU MessageFormat strings.") default_disabled = True + version_added = "4.9" def __init__(self) -> None: super().__init__() @@ -290,6 +291,7 @@ class ICUMessageFormatCheck(ICUCheckMixin, BaseFormatCheck): description = gettext_lazy( "Syntax errors and/or placeholder mismatches in ICU MessageFormat strings." ) + version_added = "4.9" def check_format(self, source: str, target: str, ignore_missing, unit: Unit): """Checker for ICU MessageFormat strings.""" diff --git a/weblate/checks/management/commands/list_checks.py b/weblate/checks/management/commands/list_checks.py index 07c53c4994d0..4f94dcf1464a 100644 --- a/weblate/checks/management/commands/list_checks.py +++ b/weblate/checks/management/commands/list_checks.py @@ -4,12 +4,13 @@ from __future__ import annotations +from collections import defaultdict from typing import TYPE_CHECKING from weblate.checks.format import BaseFormatCheck from weblate.checks.models import CHECKS from weblate.formats.models import FILE_FORMATS -from weblate.utils.management.base import BaseCommand +from weblate.utils.management.base import DocGeneratorCommand if TYPE_CHECKING: from django_stubs_ext import StrOrPromise @@ -31,75 +32,91 @@ def escape(text: StrOrPromise): return text.replace("\\", "\\\\") -class Command(BaseCommand): - help = "List installed checks" +EXTRA_ENABLE_FLAG_DESCRIPTION = { + "rst-text": "Treat a text as an reStructuredText document, affects :ref:`check-same`.", + "bbcode-text": "Treat a text as an Bulletin Board Code (BBCode) document, affects :ref:`check-same`.", + "md-text": "Treat a text as a Markdown document, and provide Markdown syntax highlighting on the translation text area.", + "url": "The string should consist of only a URL.", +} - def flush_lines(self, lines: list[str]) -> None: - self.stdout.write("\n".join(lines)) - lines.clear() - def handle(self, *args, **options) -> None: - """List installed checks.""" - self.stdout.write(""".. - Partly generated using ./manage.py list_checks -""") - ignores: list[str] = [] - enables: list[str] = [] +class Command(DocGeneratorCommand): + help = "List installed checks" + + def add_arguments(self, parser): + super().add_arguments(parser) + parser.add_argument( + "-s", + "--sections", + nargs="*", + choices=["flags", "checks"], + help="Filter output by section. Can specify multiple sections. " + "If not specified, all sections are shown.", + ) + + def build_check_section(self, check) -> list[str]: lines: list[str] = [] - for check in sorted(CHECKS.values(), key=sorter): - check_class = check.__class__ - is_format = isinstance(check, BaseFormatCheck) - if not lines: - lines.append("\n") - lines.append(f".. _{check.doc_id}:\n") - name = escape(check.name) - lines.append(name) - if is_format: - lines.append("*" * len(name)) + check_class = check.__class__ + is_format = isinstance(check, BaseFormatCheck) + lines.append(f".. _{check.doc_id}:\n") + name = escape(check.name) + lines.append(name) + if is_format: + lines.append("*" * len(name)) + else: + lines.append("~" * len(name)) + if version_lines := check.get_versions_rst_lines(): + lines.extend(version_lines) + lines.extend(("", f":Summary: {escape(check.description)}")) + if check.glossary: + lines.append(":Scope: glossary strings") + elif check.target: + if check.ignore_untranslated: + lines.append(":Scope: translated strings") else: - lines.append("~" * len(name)) - lines.extend(("\n", f":Summary: {escape(check.description)}")) - if check.glossary: - lines.append(":Scope: glossary strings") - elif check.target: - if check.ignore_untranslated: - lines.append(":Scope: translated strings") - else: - lines.append(":Scope: all strings") - elif check.source: - lines.append(":Scope: source strings") - lines.extend( - ( - f":Check class: ``{check_class.__module__}.{check_class.__qualname__}``", - f":Check identifier: ``{check.check_id}``", - ) + lines.append(":Scope: all strings") + elif check.source: + lines.append(":Scope: source strings") + lines.extend( + ( + f":Check class: ``{check_class.__module__}.{check_class.__qualname__}``", + f":Check identifier: ``{check.check_id}``", ) - if check.default_disabled: - enable_flags: list[str] = { - check.enable_string, - *check.extra_enable_strings, - } - flags = ", ".join(f"``{flag}``" for flag in sorted(enable_flags)) - lines.append(":Trigger: This check needs to be enabled using a flag.") - - file_formats = ", ".join( - f":ref:`{file_format.format_id}`" - for file_format in FILE_FORMATS.values() - if set(file_format.check_flags) & enable_flags - ) - if file_formats: - lines.append( - f":File formats automatically enabling this check: {file_formats}" - ) - lines.append(f":Flag to enable: {flags}") - else: + ) + if check.default_disabled: + enable_flags: list[str] = { + check.enable_string, + *check.extra_enable_strings, + } + flags = ", ".join(f"``{flag}``" for flag in sorted(enable_flags)) + lines.append(":Trigger: This check needs to be enabled using a flag.") + + file_formats = ", ".join( + f":ref:`{file_format.format_id}`" + for file_format in FILE_FORMATS.values() + if set(file_format.check_flags) & enable_flags + ) + if file_formats: lines.append( - ":Trigger: This check is always enabled but can be ignored using a flag." + f":File formats automatically enabling this check: {file_formats}" ) - lines.extend((f":Flag to ignore: ``{check.ignore_string}``", "\n")) + lines.append(f":Flag to enable: {flags}") + else: + lines.append( + ":Trigger: This check is always enabled but can be ignored using a flag." + ) + lines.append(f":Flag to ignore: ``{check.ignore_string}``") + return lines - self.flush_lines(lines) + def handle(self, *args, **options) -> None: + """List installed checks.""" + sections = set(options.get("sections", []) or []) + show_all = not sections + ignores: list[str] = [] + enables: dict[str, list[str]] = defaultdict(list) + for check in sorted(CHECKS.values(), key=sorter): + self.add_section(check.doc_id, self.build_check_section(check)) ignores.extend( ( f"``{check.ignore_string}``", @@ -107,13 +124,32 @@ def handle(self, *args, **options) -> None: ) ) if check.default_disabled: - enables.extend( - ( - f"``{check.enable_string}``", - f" Enable the :ref:`{check.doc_id}` quality check.", - ) - ) + enables[check.enable_string].append(check.doc_id) - self.stdout.write("\n") - self.stdout.write("\n".join(enables)) - self.stdout.write("\n".join(ignores)) + output_file = options.get("output") + + if show_all or "checks" in sections: + self.write_sections(output_file) + + self.sections.clear() + if show_all or "flags" in sections: + enable_lines = [] + for flag, checks in enables.items(): + if len(checks) == 0: + continue + if len(checks) == 1: + enable_string = f"Enables the :ref:`{checks[0]}` quality check." + else: + enable_string = f"Enables the {', '.join([f':ref:`{check}`' for check in checks[:-1]])} and :ref:`{checks[-1]}` quality checks." + enable_lines.append(f"``{flag}``") + if flag in EXTRA_ENABLE_FLAG_DESCRIPTION: + enable_lines.append(f" {EXTRA_ENABLE_FLAG_DESCRIPTION[flag]}") + enable_lines.append(f" {enable_string}") + + self.add_section("check-flags-enables", enable_lines) + + self.add_section( + "check-flags-ignores", + ignores, + ) + self.write_sections(output_file) diff --git a/weblate/checks/markup.py b/weblate/checks/markup.py index e5f925a92d45..0f77872ce2f8 100644 --- a/weblate/checks/markup.py +++ b/weblate/checks/markup.py @@ -135,6 +135,12 @@ class BBCodeCheck(TargetCheck): name = gettext_lazy("BBCode markup") description = gettext_lazy("BBCode in translation does not match source.") default_disabled = True + versions_changed = ( + ( + "5.10", + "This checks no longer relies on unreliable automatic detection, it now needs to be turned on using the ``bbcode-text`` flag.", + ), + ) def __init__(self) -> None: super().__init__() @@ -545,6 +551,7 @@ class RSTReferencesCheck(RSTBaseCheck): description = gettext_lazy( "Inconsistent reStructuredText markup in the translated message." ) + version_added = "5.10" def get_missing_text(self, values: Iterable[str]) -> StrOrPromise: return self.get_values_text( @@ -704,6 +711,7 @@ class RSTSyntaxCheck(RSTBaseCheck): check_id = "rst-syntax" name = gettext_lazy("reStructuredText syntax error") description = gettext_lazy("reStructuredText syntax error in the translation.") + version_added = "5.10" def check_single( self, source: str, target: str, unit: Unit diff --git a/weblate/checks/placeholders.py b/weblate/checks/placeholders.py index d36f7b7616ad..188e7aa51458 100644 --- a/weblate/checks/placeholders.py +++ b/weblate/checks/placeholders.py @@ -30,6 +30,13 @@ class PlaceholderCheck(TargetCheckParametrized): default_disabled = True name = gettext_lazy("Placeholders") description = gettext_lazy("Translation is missing some placeholders.") + versions_changed = ( + ("4.3", "You can use regular expression as placeholder."), + ( + "4.13", + "With the ``case-insensitive`` flag, the placeholders are not case-sensitive.", + ), + ) @property def param_type(self): @@ -138,6 +145,12 @@ class RegexCheck(TargetCheckParametrized): default_disabled = True name = gettext_lazy("Regular expression") description = gettext_lazy("Translation does not match regular expression.") + versions_changed = ( + ( + "5.10", + "Extended support for advanced regular expressions including Unicode codepoint properties.", + ), + ) @property def param_type(self): diff --git a/weblate/checks/source.py b/weblate/checks/source.py index f4b06b32b1b1..1ddc43f5eee1 100644 --- a/weblate/checks/source.py +++ b/weblate/checks/source.py @@ -48,7 +48,7 @@ class EllipsisCheck(SourceCheck): check_id = "ellipsis" name = gettext_lazy("Ellipsis") description = gettext_lazy( - "The string uses three dots (...) instead of an ellipsis character (…)." + "The string uses three dots ``(...)`` instead of an ellipsis character ``(…)``." ) def check_source_unit(self, sources: list[str], unit: Unit): @@ -149,6 +149,7 @@ class LongUntranslatedCheck(SourceCheck, BatchCheckMixin): check_id = "long_untranslated" name = gettext_lazy("Long untranslated") description = gettext_lazy("The string has not been translated for a long time.") + version_added = "4.1" def check_source_unit(self, sources: list[str], unit: Unit) -> bool: component = unit.translation.component diff --git a/weblate/machinery/alibaba.py b/weblate/machinery/alibaba.py index de4805fa7517..7fe245ad327b 100644 --- a/weblate/machinery/alibaba.py +++ b/weblate/machinery/alibaba.py @@ -28,6 +28,8 @@ class AlibabaTranslation(MachineTranslation): "zh_Hant": "zh-tw", } + version_added = "5.3" + settings_form = AlibabaMachineryForm @cached_property diff --git a/weblate/machinery/anthropic.py b/weblate/machinery/anthropic.py index 3d1ef2edffb5..3f6b3f04e050 100644 --- a/weblate/machinery/anthropic.py +++ b/weblate/machinery/anthropic.py @@ -22,6 +22,7 @@ class AnthropicTranslation(BaseLLMTranslation): name = "Anthropic" end_point = "/v1/messages" settings_form = AnthropicMachineryForm + version_added = "5.16" def get_model(self) -> str: if self.settings["model"] == "custom": diff --git a/weblate/machinery/base.py b/weblate/machinery/base.py index a7fbc905820b..125b35b85097 100644 --- a/weblate/machinery/base.py +++ b/weblate/machinery/base.py @@ -26,6 +26,7 @@ from weblate.checks.utils import highlight_string from weblate.lang.models import Language, PluralMapper from weblate.machinery.forms import BaseMachineryForm +from weblate.utils.docs import DocVersionsMixin from weblate.utils.errors import report_error from weblate.utils.hash import calculate_dict_hash, calculate_hash, hash_to_checksum from weblate.utils.requests import http_request @@ -81,7 +82,7 @@ class GlossaryDoesNotExistError(MachineTranslationError): """Raised when glossary deletion fails because it does not exist.""" -class BatchMachineTranslation: +class BatchMachineTranslation(DocVersionsMixin): """Generic object for machine translation services.""" name = "MT" diff --git a/weblate/machinery/cyrtranslit.py b/weblate/machinery/cyrtranslit.py index 6a9d3b77535e..5139f9588920 100644 --- a/weblate/machinery/cyrtranslit.py +++ b/weblate/machinery/cyrtranslit.py @@ -53,6 +53,7 @@ class CyrTranslitTranslation(MachineTranslation): name = "CyrTranslit" max_score = 100 + version_added = "5.7" cache_translations = False replacement_start = "[___" replacement_end = "___]" diff --git a/weblate/machinery/libretranslate.py b/weblate/machinery/libretranslate.py index bfae80fe2a1f..48a1a6774b44 100644 --- a/weblate/machinery/libretranslate.py +++ b/weblate/machinery/libretranslate.py @@ -22,6 +22,7 @@ class LibreTranslateTranslation(BatchMachineTranslation): name = "LibreTranslate" max_score = 89 + version_added = "4.7.1" settings_form = LibreTranslateMachineryForm request_timeout = 20 diff --git a/weblate/machinery/management/commands/list_machinery.py b/weblate/machinery/management/commands/list_machinery.py index 8bab493df275..423629965795 100644 --- a/weblate/machinery/management/commands/list_machinery.py +++ b/weblate/machinery/management/commands/list_machinery.py @@ -5,11 +5,11 @@ from __future__ import annotations from weblate.machinery.models import MACHINERY -from weblate.utils.management.base import BaseCommand +from weblate.utils.management.base import DocGeneratorCommand from weblate.utils.rst import format_table -class Command(BaseCommand): +class Command(DocGeneratorCommand): help = "List installed machineries" @staticmethod @@ -30,17 +30,20 @@ def get_help_text(field) -> str: def handle(self, *args, **options) -> None: """List installed add-ons.""" - self.stdout.write(""".. - Partly generated using ./manage.py list_machinery -""") for _unused, obj in sorted(MACHINERY.items()): - self.stdout.write(f".. _mt-{obj.get_identifier()}:") - self.stdout.write("\n") - self.stdout.write(obj.name) - self.stdout.write("-" * len(obj.name)) - self.stdout.write("\n") - self.stdout.write(f":Service ID: ``{obj.get_identifier()}``") - self.stdout.write(f":Maximal score: {obj.max_score}") + machinery_content = [] + machinery_content.extend( + [ + f".. _mt-{obj.get_identifier()}:", + "", + obj.name, + "-" * len(obj.name), + *obj.get_versions_rst_lines(), + "", + f":Service ID: ``{obj.get_identifier()}``", + f":Maximal score: {obj.max_score}", + ] + ) features = [] if obj.highlight_syntax: features.append(":ref:`placeables-mt`") @@ -49,7 +52,7 @@ def handle(self, *args, **options) -> None: if features: prefix = ":Advanced features: " for feature in features: - self.stdout.write(f"{prefix}* {feature}") + machinery_content.append(f"{prefix}* {feature}") if not prefix.isspace(): prefix = " " * len(prefix) @@ -61,12 +64,16 @@ def handle(self, *args, **options) -> None: ] prefix = ":Configuration: " for table_row in format_table(table, None): - self.stdout.write(f"{prefix}{table_row}") + table_row = table_row.strip( + "\n" + ) # self.write_sections() inserts newlines + machinery_content.append(f"{prefix}{table_row}") if not prefix.isspace(): prefix = " " * len(prefix) + machinery_content.append("") else: - self.stdout.write( + machinery_content.append( ":Configuration: `This service has no configuration.`" ) - self.stdout.write("\n") - self.stdout.write("\n") + self.add_section(obj.get_identifier(), machinery_content) + self.write_sections(options.get("output")) diff --git a/weblate/machinery/modernmt.py b/weblate/machinery/modernmt.py index 9a2185a1158b..3941f90c15ae 100644 --- a/weblate/machinery/modernmt.py +++ b/weblate/machinery/modernmt.py @@ -33,6 +33,7 @@ class ModernMTTranslation(GlossaryMachineTranslationMixin): name = "ModernMT" max_score = 90 settings_form = ModernMTMachineryForm + version_added = "4.2" language_map: ClassVar[dict[str, str]] = { "fa": "pes", diff --git a/weblate/machinery/ollama.py b/weblate/machinery/ollama.py index 60b243abbbbc..f66e43ec32f5 100644 --- a/weblate/machinery/ollama.py +++ b/weblate/machinery/ollama.py @@ -24,6 +24,7 @@ class OllamaTranslation(BaseLLMTranslation): name = "Ollama" end_point = "/api/chat" settings_form = OllamaMachineryForm + version_added = "5.15" def get_model(self) -> str: return self.settings["model"] diff --git a/weblate/machinery/openai.py b/weblate/machinery/openai.py index c07d5eb3880c..b0e3ab45dec2 100644 --- a/weblate/machinery/openai.py +++ b/weblate/machinery/openai.py @@ -71,6 +71,8 @@ def fetch_llm_translations( class OpenAITranslation(BaseOpenAITranslation): name = "OpenAI" + version_added = "5.3" + settings_form = OpenAIMachineryForm def __init__(self, settings=None) -> None: @@ -112,6 +114,7 @@ def get_model(self) -> str: class AzureOpenAITranslation(BaseOpenAITranslation): name = "Azure OpenAI" + version_added = "5.8" settings_form = AzureOpenAIMachineryForm def __init__(self, settings=None) -> None: diff --git a/weblate/machinery/tests.py b/weblate/machinery/tests.py index a1434518956a..9fc4ebf5cca0 100644 --- a/weblate/machinery/tests.py +++ b/weblate/machinery/tests.py @@ -3283,7 +3283,7 @@ def test_configure_invalid(self) -> None: class CommandTest(FixtureTestCase): """Test for management commands.""" - def test_list_addons(self) -> None: + def test_list_machinery(self) -> None: output = StringIO() call_command("list_machinery", stdout=output) self.assertIn("DeepL", output.getvalue()) diff --git a/weblate/machinery/yandexv2.py b/weblate/machinery/yandexv2.py index 9604a031cb72..ccc809e470e7 100644 --- a/weblate/machinery/yandexv2.py +++ b/weblate/machinery/yandexv2.py @@ -27,6 +27,7 @@ class YandexV2Translation(MachineTranslation): name = "Yandex v2" max_score = 90 settings_form = KeyMachineryForm + version_added = "5.1" def check_failure(self, response: Response) -> None: super().check_failure(response) diff --git a/weblate/utils/docs.py b/weblate/utils/docs.py index cf8e54a2e4d3..2d86b215ca33 100644 --- a/weblate/utils/docs.py +++ b/weblate/utils/docs.py @@ -3,7 +3,8 @@ # SPDX-License-Identifier: GPL-3.0-or-later from __future__ import annotations -from typing import TYPE_CHECKING +import textwrap +from typing import TYPE_CHECKING, ClassVar from django.conf import settings from django.utils.translation import get_language @@ -32,3 +33,26 @@ def get_doc_url(page: str, anchor: str = "", user: User | None = None) -> str: anchor = f"#{anchor}" # Generate URL return f"https://docs.weblate.org/{code}/{doc_version}/{page}.html{anchor}" + + +class DocVersionsMixin: + """ + Mixin for classes that document version metadata in RST. + + Set version_added and/or versions_changed on subclasses; get_versions_output() + renders them as .. versionadded:: and .. versionchanged:: directives. + """ + + version_added: ClassVar[str | None] = None + versions_changed: ClassVar[tuple[tuple[str, str], ...]] = () + + @classmethod + def get_versions_rst_lines(cls) -> list[str]: + parts: list[str] = [] + if cls.version_added is not None: + parts.extend(["", f".. versionadded:: {cls.version_added}"]) + for version, description in cls.versions_changed: + normalized = description.replace("\r\n", "\n").replace("\r", "\n") + body = textwrap.indent(normalized, " ") + parts.extend(("", f".. versionchanged:: {version}", "", body)) + return parts diff --git a/weblate/utils/management/base.py b/weblate/utils/management/base.py index 4b53c7170c6e..c84343833a2a 100644 --- a/weblate/utils/management/base.py +++ b/weblate/utils/management/base.py @@ -6,7 +6,8 @@ from __future__ import annotations import logging -from typing import TYPE_CHECKING +from pathlib import Path +from typing import TYPE_CHECKING, ClassVar from django.core.management.base import BaseCommand as DjangoBaseCommand from django.core.management.base import CommandError @@ -223,3 +224,73 @@ def get_translation(self, **options): def handle(self, *args, **options) -> None: raise NotImplementedError + + +class DocGeneratorCommand(BaseCommand): + sections: ClassVar[list[tuple[str, list[str]]]] = [] + + def add_arguments(self, parser): + parser.add_argument( + "-o", + "--output", + dest="output", + type=Path, + default=None, + help="Optional output file path for the generated add-ons list", + ) + + def autogenerated_markers(self, name: str) -> tuple[str, str]: + return ( + f".. AUTOGENERATED START: {name}", + f".. AUTOGENERATED END: {name}", + ) + + def insert_markers( + self, lines: list[str], start_marker: str, end_marker: str + ) -> list[str]: + command_name = self.__class__.__module__.rsplit(".", maxsplit=1)[-1] + return [ + start_marker, + f".. This section is automatically generated by `./manage.py {command_name}`. Do not edit manually.", + "", + *lines, + "", + end_marker, + ] + + def insert_content_in_lines( + self, + new_content: list[str], + lines: list[str], + start_marker: str, + end_marker: str, + ) -> list[str]: + try: + start_index = lines.index(start_marker) + end_index = lines.index(end_marker) + except ValueError: + start_index = end_index = len(lines) + + return lines[:start_index] + new_content + lines[end_index + 1 :] + + def add_section(self, section_id: str, lines: list[str]) -> None: + self.sections.append((section_id, lines)) + + def write_sections(self, output_file: Path | None) -> None: + if output_file: + lines = output_file.read_text(encoding="utf-8").splitlines() + for section_id, section_lines in self.sections: + start_marker, end_marker = self.autogenerated_markers(section_id) + block = self.insert_markers(section_lines, start_marker, end_marker) + lines = self.insert_content_in_lines( + block, + lines, + start_marker, + end_marker, + ) + output_file.write_text("\n".join(lines) + "\n", encoding="utf-8") + else: + for section_id, section_lines in self.sections: + start_marker, end_marker = self.autogenerated_markers(section_id) + block = self.insert_markers(section_lines, start_marker, end_marker) + self.stdout.write("\n".join(block))