What does the # language: header at the top of a Cucumber feature file change, and what breaks when it is missing?

## What the header is, and how the dialect is chosen Gherkin is localized. The keywords the parser accepts — `Feature`, `Background`, `Scenario`, `Examples`, `Given`, `When`, `Then`, `And`, `But` — have translations in a large number of languages, and Cucumber picks which set applies **per file** from a header written in comment form on the first line: ``` # language: fr Fonctionnalité: Commande de repas scolaires ``` The header looks like a comment because it *is* comment-shaped — `#` followed by `language:` and a language code. It must come at the top of the file, above the feature header. There is no auto-detection: without the header the parser uses the default dialect, English. The keyword tables themselves are not invented per implementation. They live in the Gherkin project's own `gherkin-languages.json`, which every Cucumber implementation ships, so `# language: fr` means the same keywords in Cucumber-JVM, cucumber-js, Behave and SpecFlow/Reqnroll. ## What it changes — and what it does not The header changes **the vocabulary the parser recognises**, and nothing else. | Element | Translated by the header? | |---|---| | `Feature`, `Rule`, `Background`, `Scenario`, `Examples` keywords | yes | | `Given` / `When` / `Then` / `And` / `But` step keywords | yes | | The `*` bullet step keyword | no — it is valid in every dialect | | The **text** of a step, after the keyword | no — you write it in whatever language you like | | Step-definition code, expressions and parameter types | no | | Tag names | no — tags are names your team invents | | Table and doc-string syntax | no — `\|` and the triple-quote delimiter are universal | The consequence people miss: because the step keyword is stripped before a step is matched to a step definition, **translating keywords does not change your glue layer at all**. A French feature file whose steps read `Quand un parent commande 2 repas` needs a step definition whose expression matches `un parent commande 2 repas`. It is the step *text* — which the header never touches — that decides whether your glue matches. So a team writing French keywords with English step text is perfectly valid, and a team writing English keywords with French step text is equally valid; the header only governs the first word of each line. An extra subtlety worth knowing: in some dialects a step keyword is not followed by a space at all, because the language does not use one. The keyword table, not a "split on the first space" rule, defines where the keyword ends and the step text begins. ## When the header is missing, misspelled or in the wrong place If a file uses localized keywords and the header is absent, misspelled, or written below the `Feature` line, the parser falls back to English keywords. `Fonctionnalité:` then matches no known keyword, and the file fails to parse — Cucumber reports a syntax error for that file rather than running its scenarios or reporting them as undefined. The failure is loud, which is the good news: you find out at parse time, not through a silently skipped feature. Because the header is per file, a suite can mix dialects — one file in French, another in English — and each is parsed with its own keyword table. There is no way to write two dialects inside one file. ## Practical guidance - **Pick one dialect per suite** and enforce it in review. On a school-meal ordering service where a kitchen-operations team writes scenarios in French and a platform team writes them in English, the parse still works, but the suite reads as two products and the shared step text drifts into two vocabularies. - **Localize the keywords only if the readers are non-English speakers.** The value of a dialect is that a domain expert can read the file. If everyone who reads it works in English, translated keywords buy nothing and cost you tooling friction — editor plugins, snippet generation and third-party report viewers all handle the default dialect best. - **Never localize half a file.** Since the dialect is chosen once per file, a single English `Scenario:` in a French file simply does not parse. - **Remember the header is the first line.** A tag line or a licence comment pushed above it is the usual cause of a mysterious "this worked yesterday" parse failure after a header-stamping script runs over the repository. Interviewers rarely gate an offer on this, but it is a clean signal: a candidate who knows the header changes keywords and not step text has understood how a step reaches its definition.