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¶

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:

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:

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¶

Same placeholders — translated patterns must contain the same placeholder names as the base pattern.
Same order — placeholders must appear in the same order across all translations.
Supported languages — only en, es and pt are recognised. Unknown codes are reported by steplib validate.
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:

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

Use steplib.core.i18n.validate_i18n_consistency() programmatically:

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:

# 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 Core API Reference for the full autodoc reference of steplib.core.i18n.