Internationalization (i18n)
===========================

Steps are defined in English as the base language and translated to Spanish
(``es``) and Portuguese (``pt``). All patterns — base and translations — are
registered with behave simultaneously, so no language selection is needed at
runtime. Behave matches the pattern that corresponds to the text in the
feature file.

Supported languages
-------------------

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Code
     - Language
   * - ``en``
     - English (base, always present)
   * - ``es``
     - Spanish
   * - ``pt``
     - Portuguese

Two ways to declare translations
--------------------------------

1. ``i18n`` dictionary (recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Pass a dictionary mapping language codes to translated patterns via the
``i18n`` keyword argument of ``@step``:

.. code-block:: python

   from steplib import step

   @step(
       "I send a {method} request to {url}",
       category="api",
       i18n={
           "es": "envío una petición {method} a {url}",
           "pt": "envio uma requisição {method} para {url}",
       },
   )
   def step_send_request(context, method, url):
       ...

The base pattern (first positional argument) is always tagged as ``en``.

2. Stacked decorators
~~~~~~~~~~~~~~~~~~~~~

Apply ``@step`` multiple times on the same function. Each call adds a new
pattern entry sharing the same implementation:

.. code-block:: python

   from steplib import step

   @step("my name is {name}", category="example")
   @step("mi nombre es {name}", category="example")
   @step("meu nome é {name}", category="example")
   def step_my_name(context, name):
       context.steplib.my_name = name

Stacked decorators are useful when translations are maintained separately or
when different backends expose different patterns for the same concept.

Rules
-----

1. **Same placeholders** — translated patterns must contain the same
   placeholder names as the base pattern.

2. **Same order** — placeholders must appear in the same order across all
   translations.

3. **Supported languages** — only ``en``, ``es`` and ``pt`` are recognised.
   Unknown codes are reported by ``steplib validate``.

4. **All patterns registered** — there is no runtime language switch. Behave
   sees every pattern and matches the one that fits the feature text.

Validation
----------

``steplib validate`` checks i18n consistency:

.. code-block:: bash

   $ steplib validate
   Placeholder mismatch for 'I send a {method} request to {url}' (lang 'es'):
   expected ['method', 'url'], got ['method']

Use :func:`steplib.core.i18n.validate_i18n_consistency` programmatically:

.. code-block:: python

   from steplib.core.i18n import validate_i18n_consistency

   errors = validate_i18n_consistency(info)
   if errors:
       for error in errors:
           print(error)

Mixing languages in a project
-----------------------------

A project can include features in English, Spanish and Portuguese without any
configuration. Behave matches the pattern that corresponds to the step text:

.. code-block:: gherkin

   # features/api_en.feature
   Feature: API health check
     Scenario: GET users
       When I send a GET request to "/users"

   # features/api_es.feature
   Feature: Chequeo de API
     Scenario: GET usuarios
       Cuando envío una petición GET a "/users"

   # features/api_pt.feature
   Feature: Verificação de API
     Scenario: GET usuários
       Quando envio uma requisição GET para "/users"

API reference
-------------

See :doc:`/api/core` for the full autodoc reference of ``steplib.core.i18n``.