weblate/docs/admin/checks.rst

Checks and fixups
=================

.. _custom-autofix:

Custom automatic fixups
-----------------------

You can also implement your own automatic fixup in addition to the standard ones and
include them in :setting:`AUTOFIX_LIST`.

The automatic fixes are powerful, but can also cause damage; be careful when
writing one.

For example, the following automatic fixup would replace every occurrence of the string
``foo`` in a translation with ``bar``:

.. literalinclude:: ../../weblate/examples/fix_foo.py
    :language: python

To install custom checks, provide a fully-qualified path to the Python class
in the :setting:`AUTOFIX_LIST`, see :ref:`custom-check-modules`.

.. _custom-checks:

Customizing behavior using flags
--------------------------------

You can fine-tune Weblate's behavior by using flags. The flags provide visual
feedback to the translators and help them to improve their translation.
The flags are merged from following sources:

* Source string additional flags:

  * :ref:`additional` describes manual editing.
  * :ref:`bulk-edit` can be used to apply flags in batch.
  * :ref:`addon-weblate.flags.bulk` add-on can apply flags automatically.

* Per-string flags extracted from the file format, see :ref:`formats`.
* Translation flags (currently only ``read-only`` flag for bilingual source string or when monolingual template editing is turned off).
* File-format specific flags.
* :ref:`component` (:ref:`component-check_flags`).
* :ref:`project` (:ref:`project-check_flags`).

The flags are comma-separated; if they have parameters, they are separated
with colon. You can use quotes to include whitespaces or special characters
in the string. For example:

.. code-block:: text

   placeholders:"special:value":"other value", regex:.*

Both single and double quotes are accepted, special characters are being escaped using backslash:

.. code-block:: text

   placeholders:"quoted \"string\"":'single \'quoted\''

.. code-block:: text

   placeholders:r"^#*"

To verify that translators do not change the heading of a Markdown document.
A failing check will be triggered if the string ``### Index`` is translated as ``# Indice``.

.. code-block:: text

   placeholders:r"\]\([^h].*?\)"

To ensure that internal links are not being translated (i.e. `[test](../checks)`
does not become `[test](../chequeos)`.

The flags defined on a higher level can be discarded using the
``discard:NAME`` syntax. For example, if a component is configured to
``safe-html``, you can add ``discard:safe-html`` to the string flags to skip it
for this particular string.

Here is a list of flags currently accepted:

.. include:: /snippets/check-flags-autogenerated.rst

.. note::

    Generally the rule is named ``ignore-*`` for any check, using its
    identifier, so you can use this even for your custom checks.

These flags are understood both in :ref:`component` settings, per source string
settings and in the translation file itself (for example in GNU gettext).

.. _location-based-flags:

Location-based flags
--------------------

Some flags are added to strings by default, based on their locations.
This means that certain checks will be automatically enabled depending on where the string is used.

* ``rst-text``: This flag is automatically added to strings in reStructuredText files, if location extension is ``.rst``.
* ``md-text``: This flag is automatically added to strings in Markdown files, if location extension is ``.md`` or ``.markdown``.

.. _enforcing-checks:

Enforcing checks
----------------

The enforced checks cannot be dismissed and mark string as :guilabel:`Needs
editing` (see :ref:`states`). This prevents translators from hiding such
checks.

.. hint::

   Turning on check enforcing doesn't enable it automatically. Some checks have
   to be turned on by adding the corresponding flag to the string or component
   flags.

This is best used with checks that can cause serious issues when used like
checks for :ref:`check-formats`. Using for style checks like :ref:`check-same`
is not recommended because dismissal is sometimes a reasonable approach in these.

The :ref:`project-commit_policy` can then be used to exclude strings needing
editing from being committed to the version control.


.. seealso::

   * :ref:`states`
   * :ref:`component-enforced_checks`
   * :ref:`project-commit_policy`
   * :ref:`additional`
   * :ref:`component-check_flags`

.. _fonts:

Managing fonts
--------------

.. hint::

   Fonts uploaded into Weblate are used purely for purposes of the
   :ref:`check-max-size` check, they do not have an effect in Weblate user
   interface.

The :ref:`check-max-size` check used to calculate dimensions of the rendered
text needs font to be loaded into Weblate and selected using a translation flag
(see :ref:`custom-checks`).

Weblate font management tool in :guilabel:`Fonts` under the :guilabel:`Operations`
menu of your translation project provides interface to upload and manage fonts.
TrueType or OpenType fonts can be uploaded, set up font-groups and use those in
the check.

The font-groups allow you to define different fonts for different languages,
which is typically needed for non-latin languages:

.. image:: /screenshots/font-group-edit.webp

The font-groups are identified by name, which can not contain whitespace or
special characters, so that it can be easily used in the check definition:

.. image:: /screenshots/font-group-list.webp

Font-family and style is automatically recognized after uploading them:

.. image:: /screenshots/font-edit.webp

You can have a number of fonts loaded into Weblate:

.. image:: /screenshots/font-list.webp

To use the fonts for checking the string length, pass it the appropriate
flags (see :ref:`custom-checks`). You will probably need the following ones:

``max-size:500`` / ``max-size:300:5``
   Defines maximal width in pixels and, optionally, the maximum number of lines (word wrapping is applied).
``font-family:ubuntu``
   Defines font group to use by specifying its identifier.
``font-size:22``
   Defines font size in pixels.


.. _own-checks:

Writing own checks
------------------

A wide range of quality checks are built-in, (see :ref:`checks`), though
they might not cover everything you want to check. The list of performed checks
can be adjusted using :setting:`CHECK_LIST`, and you can also add custom checks.

1. Subclass the `weblate.checks.Check`
2. Set a few attributes.
3. Implement either the ``check`` (if you want to deal with plurals in your code) or
   the ``check_single`` method (which does it for you).

Some examples:

To install custom checks, provide a fully-qualified path to the Python class
in the :setting:`CHECK_LIST`, see :ref:`custom-check-modules`.

Checking translation text does not contain "foo"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a pretty simple check which just checks whether the translation is missing
the string "foo".

.. literalinclude:: ../../weblate/examples/check_foo.py
    :language: python

Checking that Czech translation text plurals differ
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Check using language info to verify the two plural forms in Czech
language are not same.

.. literalinclude:: ../../weblate/examples/check_czech.py
    :language: python