.. role:: bash(code)
   :language: bash

********
Examples
********

In this document, we detail a few more involved examples with project
configurations.

.. _excludes_example:

Handling Excludes
=================

Say, you want to use two localization flows for a project.
You have one general workflow, but also an exceptional workflow for
some sub-parts of your project. This can be implemented with a hierarchy
of included and excluded configuration files. As excludes are only allowed
in the top-level configuration files, it requires a few files, but it also
provides a clear structure.

Overview
--------

These are the configuration files we're going to use:

.. code-block::

    l10n-general.toml
    l10n-exception.toml
    configs/
        general.toml
        exception.toml
        never.toml

Entry points
------------

There are two entry points, one for each workflow. :bash:`l10n-general.toml` is the
entry point for the general workflow, while :bash:`l10n-exception.toml` is the other.
Both only contain includes and excludes.

:bash:`l10n-general.toml`:

.. code-block:: toml

    basepath = "."

    [[includes]]
        path = "configs/general.toml"

    [[excludes]]
        path = "configs/exception.toml"

    [[excludes]]
        path = "configs/never.toml"

:bash:`l10n-exception.toml`:

.. code-block:: toml

    basepath = "."

    [[includes]]
        path = "configs/exception.toml"

    [[excludes]]
        path = "configs/never.toml"

Child configs
-------------

These configs include the actual configuration content, including locale
lists et al. They all start with the same preamble to set the base path to
the top of the project:

.. code-block:: toml

    basepath = ".."

Then they list the locales they cover, and some ``[[paths]]`` configurations.
In practice, they could also have further ``[[includes]]`` instructions.

:bash:`configs/general.toml`

.. code-block:: toml

    basepath = ".."
    locales = ["de", "fr", "it"]
    [[paths]]
        reference = "en/**"
        l10n = "{locale}/**"


:bash:`configs/exception.toml`

.. code-block:: toml

    basepath = ".."
    locales = ["de", "fr"]
    [[paths]]
        reference = "en/special/**"
        l10n = "{locale}/special/**"


:bash:`configs/never.toml`

.. code-block:: toml

    basepath = ".."
    [[paths]]
        reference = "en/special/feature-without-german.ftl"
        l10n = "{locale}/special/feature-without-german.ftl"
        locales = ["de"]

Resulting Matches
-----------------

This leads to the following paths triggering these configurations:

*General*
^^^^^^^^^

.. list-table::
   :widths: auto
   :header-rows: 1

   * - File
     - ``de``
     - ``fr``
     - ``it``
   * - ``some-feature.ftl``
     - X
     - X
     - X
   * - ``special/feature.ftl``
     -
     -
     - X
   * - ``special/feature-without-german.ftl``
     -
     -
     - X

*Exception*
^^^^^^^^^^^

.. list-table::
   :widths: auto
   :header-rows: 1

   * - File
     - ``de``
     - ``fr``
     - ``it``
   * - ``some-feature.ftl``
     -
     -
     -
   * - ``special/feature.ftl``
     - X
     - X
     -
   * - ``special/feature-without-german.ftl``
     -
     - X
     -