Gherkin Language Beyond English: Keywords in Other Languages

The Gherkin language isn’t limited to English. A team can write Given, When and Then in French, Hindi, German and dozens of other languages. This post shows how it works, with one scenario written three ways, and where it stops helping.

Gherkin in One Minute

Gherkin is a plain-text format for describing how software should behave. You save it in a .feature file. Each scenario is a short story made of steps, and each step starts with a keyword. Given sets the starting point. When is the action. Then is the expected result. And continues the step before it.

Feature: Renew a book
  Scenario: Renew a book that nobody has reserved
    Given I have borrowed a book
    And nobody has reserved the book
    When I ask to renew it
    Then the due date moves forward by 14 days

Tools such as Cucumber read the file and run code attached to each sentence. Only the keywords are fixed. The sentence after each keyword is free text. That’s why the Gherkin language can move to another spoken language and keep its structure.

The Language Header

To write in another language, put one comment line at the top of the file. It looks like # language: fr, and it tells the parser which keyword list to use. Without it, the parser expects English.

I checked this with the official Gherkin parser for Python, version 42.0.1. Its keyword file lists 80 languages. Here is the same scenario in French.

# language: fr
Fonctionnalité: Renouveler un livre
  Scénario: Renouveler un livre que personne n'a réservé
    Soit un livre emprunté
    Et que personne ne l'ait réservé
    Quand je demande le renouvellement
    Alors la date de retour avance de 14 jours

Feature became Fonctionnalité, Scenario became Scénario, and Given became Soit. The parser reported language fr and four steps. It labeled them Context, Conjunction, Action and Outcome, exactly as it did for the English file. That’s the key point. Every language maps to the same four step types, so a tool treats a French file like an English one.

Here is the same scenario in Hindi. The parser read it as language hi, with the same four steps.

# language: hi
रूप लेख: किताब का नवीनीकरण
  परिदृश्य: ऐसी किताब का नवीनीकरण जिसे किसी ने आरक्षित नहीं किया
    अगर एक किताब उधार ली गई है
    और किसी ने उस किताब को आरक्षित नहीं किया है
    जब नवीनीकरण का अनुरोध किया जाता है
    तब वापसी की तारीख 14 दिन आगे बढ़ जाती है

The same file also holds two joke languages, Pirate and LOLCAT. In Pirate, Feature is “Ahoy matey!” and Given is “Gangway!”. Nobody should write real tests that way, but it proves a point. The keywords are a lookup table, not magic. A new language is only a new column of words.

Each language lists several words for one keyword, so teams can pick the one that reads best. This table shows one word per keyword, taken from the same keyword file.

Why This Helps a Team

The people who know a business rule best don’t always think in English. A clerk, an accountant or a support lead spots a wrong rule faster in their own language. A scenario they can read is a scenario they will review.

Local terms also stay intact. A legal or tax word has an exact meaning at work, and a translation can blur it. Writing the step in the word everyone already uses removes one source of confusion.

New team members benefit too. A scenario is the shortest description of what the software does. Reading it in their first language makes the product easier to learn.

Review meetings change as well. When the rule is written in the language of the meeting, people stop translating in their heads. They start arguing about the rule itself, and that’s the conversation the whole approach is meant to start. A translation can hide a disagreement, but the team’s own words expose it.

Where It Stops Helping

A header is a promise, and the parser keeps you to it. I tried three ways of breaking it. First, I wrote French keywords with no header. The parser stopped with three errors, one for each line, because it expected English words.

Second, I put the header after the Feature line. Nothing failed. The parser treated it as an ordinary comment and read the file as English. Keep the header on the first line.

Third, I wrote an English Given line inside a French file. This one is the dangerous case, because there was no error at all. The parser found a scenario with zero steps and kept the English line as description text. A scenario with no steps checks nothing, so look at the step count when you switch languages.

The code side has limits too. Step definitions match the sentence text, so a French sentence needs a French pattern in code. Cucumber for Java also offers step annotations named in other languages. Translating the keywords doesn’t translate the code.

The Case for English Anyway

You could say that English is safer. Code, error messages and tickets are already in English, and a mixed team can read every file. Fair point.

The answer depends on who reads the scenarios. If only engineers read them, English costs nothing. If a product owner or a regulator must approve them, their language wins. Don’t keep two translated copies of one feature. They drift apart, and then nobody knows which one is correct.

A Short Checklist

• Put # language: on the first line of the file.
• Use one language per file, and one language per feature.
• Pick the keyword that reads best, since each language offers several.
• Print the parsed steps once and check the count.
• Write step patterns in the same language as the sentences.

Start with one feature that the business owns. Write it in their language and let them review it. The result tells you more than any argument about tools.

If your team doesn’t work in English, plan the glue code when you adopt the Gherkin language. Agree on how step patterns are named. Decide who owns the wording of each rule. Write the keyword choices down once. Ten minutes of agreement saves a long review later. Without it, two people write the same step in two different words.

A Gherkin file in your team’s language is not a translation job, it is a review everyone can join.

Published by Pinal Dave on SQLAuthority. More of my work at pinaldave.com.