Translation is not finished when a feature file sounds natural
How can people translate Cucumber Gherkin feature files quickly while keeping automated acceptance tests working? They separate Gherkin’s localised grammar keywords from the scenario text that a project’s step definitions actually match, then map every change through a test run. Gherkin translation involves translating Feature, Scenario, Given, When and Then into an accepted dialect when appropriate, but it also involves preserving the connection between the words that describe behaviour and the code that performs the assertions. A well-written French or Malay scenario that no longer matches a step definition is readable documentation but a broken executable specification.
Consider a school enrolment portal. In English, a scenario says that a parent submits a completed form and then receives a receipt number. The target-language feature might correctly describe the receipt, yet a test runner reports an undefined step because its implementation recognises only the original English sentence. Conversely, a translator could preserve execution by leaving an English step untouched while quietly translating the surrounding explanation to say that an approval rather than an acknowledgement is issued. The test would pass while the translated document gave parents and product owners the wrong assurance. Both failures matter, and neither can be detected through spelling checks alone.
The safe fast method is to inventory existing step expressions, choose a supported Gherkin spoken-language dialect, translate the behavioural contract in context, adapt bindings only under engineering control, and run the target-language scenarios in continuous integration. This guide explains how to translate Gherkin .feature files, how to localise Cucumber acceptance-test scenarios and how to diagnose undefined or ambiguous steps without mixing translation with unapproved application changes. Its purpose is one bounded job: make an existing executable specification understandable in another language while keeping its tested promise intact.
What the file actually contains
A feature file is plain text with syntax meaningful to a Gherkin parser. A Feature introduces the capability, a scenario describes an example, and steps state the precondition, action and observable outcome. Rule, Background, scenario outlines and example tables let a team organise many related examples. Comments, tags and Doc Strings carry additional context. The same file is both a reading surface for stakeholders and a structured input for a test runner, so translation needs two kinds of quality assurance rather than only a literary editor.
Cucumber’s official reference explains that Gherkin keywords are localised into multiple spoken languages. A file can declare the language near its beginning with a line such as # language: fr; without a declaration, English is the normal default. The list of permissible words is defined by Cucumber’s maintained language registry, not by a translator’s instinct. For example, a natural dictionary equivalent for Then is not necessarily an accepted keyword in the chosen dialect. A parser has to recognise the word exactly as a keyword before it can consider the step’s meaning.
The words after the step keyword are a different layer. When Cucumber encounters a step, it searches the project’s step definitions for a matching expression. Those definitions may use a regular expression or a Cucumber Expression, perhaps with parameters. Therefore replacing Given with a supported local keyword can preserve the matching text, but replacing the rest of the line can make the expression fail. Do not assume that internationalising the grammar automatically internationalises the binding code. This distinction is the central technical boundary in this translation task.
Define the acceptance contract before changing language
Obtain the original .feature files, their version-control commit, the matching step-definition sources, sample test output and the target language agreed with product owners. Record the Cucumber language implementation and version used by the project, since availability of keywords and configuration paths may differ across implementations. Determine whether the target-language file replaces the original, runs in parallel as a translated suite, or is published for review while only one canonical executable suite remains. These are different release strategies with different maintenance costs.
Ask the product owner what each assertion really guarantees. In a school fee workflow, ‘payment accepted’ can mean a gateway accepted the transaction, money settled, an invoice became paid, or the portal merely accepted a request to pay. Translate the existing guarantee instead of deciding what a better product should do. Ask whether example values are meaningful contracts: a currency symbol, date boundary, age, grade, status or role may be deliberate test data and not optional local flavour. Document the difference between essential values and harmless examples before translators choose culturally familiar replacements.
Create an ownership table with feature path, scenario title, original step text, step-definition identifier, parameter capture, example-data dependencies, intended observation and translation reviewer. A source scenario may be written by a developer but owned semantically by an admissions administrator. The technical owner can tell whether the step still executes; the administrator can tell whether the outcome is true to the policy. Both checks are required. Assign a named reviewer for ambiguous statements instead of letting a translation vendor decide the product’s hidden behaviour.
Begin with one small scenario and trace every connection
Take a simple test: the parent submits a complete application, the system stores it, and a receipt appears. Identify which steps create the parent, submit the application and inspect the receipt. Do not translate the three lines as unrelated sentences. The actor’s identity in the first step may determine which account is used in the second. The final assertion may check a database record or only a visible message. A translated sentence about ‘receiving an official approval’ cannot be justified by an assertion that merely checks that a receipt field exists.
Compare each proposed target step with the matching code. If the expression is the applicant submits a complete form, the target sentence cannot execute through that expression unless the project adds or adjusts a binding or deliberately retains the original matching phrase. Teams can choose to create language-specific step definitions that call shared helper functions, or maintain a stable canonical language for executed steps and provide a separate translated reading layer. What matters is that this decision is explicit. An automated file translation service cannot infer which architectural path the project has already chosen.
When testing, distinguish a parser error from an undefined step, an ambiguous binding and an application assertion failure. A parser error may mean an unsupported keyword or malformed table. An undefined step can mean the sentence has no matching definition. Ambiguity means multiple definitions match. A failed assertion means the code executed but found the behaviour absent or different. Treating all four as translation mistakes wastes time and can encourage dangerous changes to make the test green without understanding why it was red.
Localise Gherkin keywords with the declared dialect
The opening # language: directive is a syntax instruction, not a comment to translate freely. A project using French might start with # language: fr followed by the supported French equivalents for Feature and Scenario. Check the exact keywords against the Cucumber language registry; some languages provide several synonyms, and punctuation rules still matter. Not every translated word follows a colon. The keyword syntax defines a parse tree, while the text after the keyword communicates business meaning. Validate both separately before reviewing style.
Do not automatically change the language code because the file contains a phrase in another language. A bilingual school might intentionally keep executable steps in English while quoting a Chinese message in a Doc String. A file’s Gherkin dialect is about grammar tokens, not the language of every literal value. Similarly, a source feature with the directive only in a template file may be controlled by runner configuration. Inspect the actual test setup so that a translation does not introduce conflicting language declarations or break feature discovery.
A translator might think translating a Scenario Outline heading is sufficient. In fact, the supported term, Examples heading, row structure and angle-bracket placeholders all have syntax roles. If a target dialect lacks a term a translator wanted to use, choose an actual supported synonym rather than inventing a closer phrase. If the team is still learning to read the target dialect, provide a bilingual vocabulary sheet mapping each Gherkin keyword to its accepted spelling. That is a small investment that prevents recurring parser defects.
Keep behaviour and test bindings aligned
Cucumber’s step matching generally ignores whether the line begins with Given, When or Then; the body of the step is what a definition matches. This means changing a step keyword can change the story’s logic for human readers without necessarily changing which code runs. If a translator changes ‘Then the receipt is visible’ to a target phrase meaning ‘When the receipt appears’, the binding might still execute while the specification’s precondition/action/result sequence becomes confusing. Review the three-part behaviour, not just the raw match count.
Use parameter names, domain glossary and expression matching together. A step definition may bind {int}, {word} or a custom parameter type, and its regular expression may assume English words around the captured value. A target phrasing can move the number, add grammatical endings or change spacing. It is tempting to broaden a regex until everything matches. That can create ambiguity between previously distinct steps, especially if two actions differ only by a short verb. Prefer narrow, reviewed expressions that represent one behaviour; rerun the entire suite after every binding change.
Test your translated steps against both positive and negative cases. A step for ‘may submit’ is not the same as ‘must submit’, and ‘cannot approve’ is not the same as ‘does not approve’. In many languages the negative particle appears in a different position from English, making automated token substitution especially risky. A passing scenario in which only positive data was exercised cannot demonstrate that the prohibition remains correctly described. Include at least one counterexample showing the rule does not apply under another condition.
Treat scenario outlines as executable tables
A scenario outline describes a pattern with placeholders such as <status> and <expected_message>, then supplies rows in an Examples table. Those placeholder names are referenced by the scenario text and table headers. Translating one occurrence without the other may cause the outline to substitute incorrectly or leave literal angle brackets behind. Preserve the mapping between each placeholder, the table header and the values that step definitions consume. A human-facing name can be changed through a coordinated refactor, but it cannot be changed in isolation.
Example rows may contain mixed categories. A ‘role’ column could hold technical keys such as parent_admin while a ‘message’ column holds text that is genuinely translated. A ‘total’ column might be parsed as a decimal or an integer. Translating a key because it resembles ordinary English can change which account is created; swapping commas and decimal points can change a numeric boundary. Mark each column as translatable text, test fixture identifier, display exemplar, numeric input or expected output. Make a decision for every column rather than bulk translating all cells.
For a boundary case, suppose a registration closes at a particular local time. An examples row uses a timestamp deliberately one minute before closing and another one minute after. Reformatting the display may be reasonable, but moving the moment to a different timezone can change which case passes. Preserve the intended instant and offset unless the test’s purpose is specifically to validate local timezone behaviour. Distinguish translating a visible date label from changing a machine-readable timestamp that participates in the assertion.
Control Doc Strings, data tables, tags and comments
Doc Strings carry multi-line arguments to a step. They might contain an email body, JSON request, XML response, a message template or prose. A translator should inspect the step definition to learn how that payload is consumed. A JSON example containing technical property names and a natural-language message can be partially translated, but only if its schema and test assertions permit that change. A literal string used as a golden comparison may need its expected fixture updated together with the application locale; changing only the .feature file could create a false failure.
Gherkin data tables resemble small spreadsheets. Their pipe delimiters and row-to-column structure must survive translation. Do not combine cells to make a target phrase read more naturally, and do not move a value into the next column merely because a longer word wraps in an editor. The first row may serve as map keys passed into code rather than presentation headings. Determine whether header text is a parser-facing key before localising it. Retain escaping where a value itself contains a pipe or other meaningful punctuation.
Tags often select test groups, environments or release priorities. A tag such as @smoke, @admissions or @requires_database may be referenced by CI filters and command-line expressions. Translating the tag can silently drop scenarios from a pipeline if the filter still looks for the original string. Comments can usually be localised more freely, but comments containing maintenance directives, issue IDs or parser hints need separate treatment. The quick, safe principle is that typography does not determine whether a token is technical: inspect how the project uses it.
Verify the translated file with a focused execution loop
Use a branch or copy and change one feature first. Parse it with the project’s actual Gherkin implementation, print the discovered scenarios and confirm that all intended examples remain present. Run a dry-run or step-discovery mode where supported to identify undefined or ambiguous steps without altering production data. Then run the scenarios in an isolated test environment. Record outcomes at parser, binding, fixture and assertion layers so reviewers can diagnose a red result without guessing whether the problem is grammatical or functional.
Compare the original and translated suite at the behaviour level. A practical ledger contains scenario identity, rule covered, examples count, fixture contract, expected outcome and actual result. Source and target headings need not be word-for-word equivalents, but both must cover the same behavioural obligation. If translation causes a scenario to be skipped by a tag filter, a naive report of ‘all translated tests passing’ is meaningless. Count discovered, executed, skipped and failed scenarios. Investigate any missing scenario before approving the localized suite.
Release only after a domain expert reads the target language against realistic use. A passing test does not prove that a translation correctly communicates consent, authority, refunds, eligibility or retention. It proves the configured code found its expected behaviour for tested inputs. A target-language review should walk from condition to action to result and ask whether a nontechnical user would infer the same obligation as the source. Store the reviewer decision with the commit so the next revision does not repeat the same ambiguity.
Worked example: parent consent and a test that almost lied
Imagine a consent workflow tested in a .feature file. The source rule says a field-trip application can be submitted only after a parent has given consent. The tester sets consent=true, selects a trip and submits the form. The outcome checks that the application status becomes ‘received’. A translator sees ‘received’ and chooses a target term normally used for ‘approved’. The software continues to produce ‘received’ and the test still passes, but a parent reading the target specification would expect permission to take part in the trip. This is a semantic defect in documentation about a working system.
The QA procedure starts by writing the intended state transition in neutral language: before submission there is a draft; after a consented submission there is a received application, pending review. The translator asks the administrative owner how the real portal labels this status in the target language. A reviewer tests a real or representative screen and verifies that the same status wording appears to parents. If the application locale deliberately uses a different approved term, the feature may explain that the status is a receipt acknowledgement rather than final approval. The outcome is a target scenario that communicates the precise evidence checked by the assertion.
Next test the negative case. A parent who has not given consent should not be able to submit, and the system should show a correction or instruction. In a scenario outline, retain separate example rows for consent given and consent absent. Avoid deleting the latter because it takes time to translate an error message. Losing it reduces test coverage at the exact point where localised policy language often creates misunderstandings. Include the expected error as target-language content only if the application under test actually produces that target text in its locale. Otherwise, the feature and application changes belong in coordinated release work rather than a translation-only commit.
Finally, compare the new step text with existing definitions. If ‘the parent sees an application receipt’ maps to the original assertion, the translation can use a language-specific wrapper calling the same helper, so behaviour remains stable. If the team’s architecture forbids translated bindings, publish the translated description separately and keep executable steps in the supported canonical language. Either approach can be sound; the defect would be pretending that a translated .feature file is executable when no definition matches it. Record the chosen approach and test evidence, because the next translator must not rediscover the same integration issue.
Illustrative source and localised structure
This simplified example shows what is meant by a supported grammar dialect and a stable behavioural contract. The French keywords are examples to verify against the project’s installed Gherkin language registry before use. The target text is not guaranteed to have matching step definitions in a specific repository; the implementation must provide them. The example is deliberately short so the difference between human-readable text and executable binding remains visible.
Feature: Application receipt
Scenario: Parent submits a complete application
Given a parent has completed the required fields
When the parent submits the application
Then the portal displays a receipt number
# language: fr
Fonctionnalité: Accusé de réception de candidature
Scénario: Un parent soumet un dossier complet
Étant donné qu'un parent a rempli les champs obligatoires
Quand le parent soumet le dossier
Alors le portail affiche un numéro de réception
The principal evidence to preserve is the acknowledgement number, not a judgement on the application’s eligibility. The words ‘complete’ and ‘required’ also carry a constraint: the portal checks fields the system has designated necessary, not every possible field the parent might choose to enter. The source feature and its target should lead a stakeholder to describe the same precondition and observable result. The language directive affects Gherkin parsing; it does not install or rewrite step definitions. A real repository must execute the target scenario and show that matching expressions exist for these French step bodies.
A translation memory entry should store more than the sentence. Include the scenario’s route through application logic, the source and target audience, the assertion helper, and the particular target-language term accepted for receipt. A reviewer should see the complete scenario and the user interface, rather than a spreadsheet with ‘receipt’ in one cell. Reusing the translation for an invoice receipt may be appropriate, while reusing it for an official admission offer would be a harmful semantic collision. Context is what makes a glossary practical rather than merely alphabetic.
A specific failure: step expression becomes too broad
Suppose the English suite contains one step that checks whether a draft application was saved and another that checks whether a submitted application was accepted. A hurried localisation replaces both with a generic target phrase meaning ‘the application is recorded’. The developer broadens the binding pattern to make the translated file pass. Now one sentence can match two definitions, or a single shared helper may check only that a database row exists. Tests that once distinguished draft storage from submission can no longer express that difference. The localisation has collapsed the vocabulary of the product’s state machine.
Repair it by recovering the two observables. For a draft, the expected state might remain editable and no receipt may exist. For a submitted application, the expected state may become read-only and a receipt number may be generated. The translated steps should explicitly name those outcomes using the project’s approved terms. Implement corresponding narrow step definitions or wrapper aliases, and rerun the complete suite. A single passing scenario is insufficient; the repair must also prove that the two target phrases remain distinguishable and cannot both match the same input accidentally.
This lesson transfers beyond enrolment. ‘Book’ versus ‘request a booking’, ‘cancel’ versus ‘ask for cancellation’, ‘publish’ versus ‘save for review’, and ‘refund issued’ versus ‘refund requested’ all encode state transitions. A translator can improve speed by preparing a small state glossary for the application: the noun describing each state, the verb that causes the transition, and the visible signal that confirms it. A domain expert can approve the glossary once; later feature translations use it consistently while retaining the logical distinction of each test.
Another failure: examples were made culturally familiar
A Singapore-based team may test a cut-off rule with a fee of 500 and 501 units. A translator preparing a different locale changes the test currency and adds a thousands separator because that looks familiar to readers. If the step parser expects an integer, it may reject the formatted input. Worse, if the new currency implies a different financial threshold, the feature may assert a rule that the application never implemented. A locale should influence display conventions, but it does not grant permission to alter product policy.
Classify the numbers. A mathematical boundary such as amount greater than 500 is invariant when the test checks logical operators. A displayed currency format is locale-specific when the test deliberately checks the user interface. A value representing an actual legal fee requires domain approval and possibly different business rules in different jurisdictions. These are three different reader jobs. If the current task is translating an existing feature file, preserve the business and mathematical meaning first. A separate localisation test can demonstrate how users see the same value in their own number formatting.
Use fixtures that expose the distinction. Test a value below, equal to and above the cut-off. For rendered currency, assert the correct locale formatting separately from the predicate result. If the target file contains dates, test the boundary across timezone offsets and daylight-saving transitions only when the underlying product supports those use cases. Do not substitute a simple string comparison for a date-time comparison to make translated text easier to match. Better tests clarify what may change with the locale and what must remain invariant.
Build a glossary from behaviours rather than alphabetised words
Begin with the verbs that correspond to actions: create, save, submit, accept, reject, withdraw, cancel, archive and restore. Then record the objects of those verbs: application, consent form, payment reference, invitation, receipt and decision. Finally, record state adjectives: draft, incomplete, pending, received, approved, expired and withdrawn. This verb-object-state model helps translators recognise which distinctions are fundamental. The glossary becomes a compact map of the product’s responsibilities, not just a list of preferred synonyms.
Attach one example for each ambiguous term. ‘Withdraw application’ means the applicant intentionally retracts it; ‘reject application’ means the institution declines it. Translate both with the same broad verb and a parent may misunderstand who acted. ‘Reset password’ is an action that changes authentication credentials; ‘recover account’ may be a broader process that includes identity verification. A glossary that records the actor and outcome prevents translators from mapping two distinct features to one attractive-sounding term. Product owners should review these high-risk entries before large-scale translation begins.
Keep locale-specific terminology separate from internal code keys. A database field application_status may remain stable while its display label and values change by locale. Similarly, a Gherkin tag @eligibility may be an immutable CI selector even if the target-language section heading uses a different word. A well-designed term record contains ‘concept ID’, source expression, approved locale expression, definition, forbidden misleading alternative and note about machine identifiers. This is enough context to help another translator make correct decisions at speed without viewing the entire source repository.
Organise reviews so specialists spend time where risk is high
A two-pass review is often quicker than asking one bilingual person to evaluate everything. The first reviewer checks semantic equivalence, role and outcome using the application’s business context. The second checks Gherkin syntax, step matching, test data and execution coverage. The same person may perform both in a small team, but the checklist should still separate them. This matters because a flawless Gherkin parse does not establish that the policy was translated correctly, while elegant language does not establish that a test runner will execute it.
Triage scenarios by consequence. Instructions affecting consent, payment, access, personal data and eligibility deserve earlier domain review than a harmless confirmation message. Give priority to steps that include negative conditions, quantified words such as ‘all’ or ‘any’, strict inequalities, deadlines and role-based permissions. These patterns are common sources of translation errors that reverse the rule. A quick scan for them can find consequential defects before reviewers spend time polishing phrasing in low-risk examples. Retain the full review after this prioritisation; it is a scheduling aid, not a substitute for completeness.
Treat reviewer changes as data. If three reviewers independently change a target term, investigate whether the glossary is incomplete or the source is ambiguous. If step definitions repeatedly break when numbers appear, improve parameter mapping rather than repairing individual scenarios by hand. The purpose of a batch review is to expose reusable failure modes. After an initial quality gate, freeze accepted translations for stable concepts so later source changes can be localised without re-litigating settled terms. Keep the frozen termbase version attached to each release.
Release controls and continuous integration
Store source and target feature files alongside their step definitions in version control. A pull request should show a small, interpretable diff, not a wholesale regeneration of file formatting. Reviewers need to see whether placeholders, tags, examples and assertions changed in addition to the human wording. The automation should parse all supported dialects used by the project, enumerate expected scenarios, detect undefined and ambiguous steps, and execute tests against disposable fixture data. A pipeline that checks only English files gives false confidence about a newly translated suite.
Compare execution counts rather than relying only on a green status badge. A pipeline can pass because a translated file was not discovered, because a tag expression excluded it, or because an implementation treats undefined steps as pending without failing the build. Review configured behaviour for these states in the actual Cucumber version. The strongest evidence includes the source and target scenario list, number of example instances, match resolution, run outcome and skipped-count explanation. If the target suite is intentionally documentation-only, mark it honestly so no one mistakes a prose copy for executed regression protection.
Avoid unattended updates to production tests or business rules. The translation deliverable may include suggestions for adjusting step definitions, fixtures or application locale resources, but those changes affect software behaviour and belong to their owners. Preserve an auditable change request for each proposed binding update. Review target-language screenshots separately if the test asserts on UI strings. If a translation changes a user-facing message, the product’s locale bundle and the feature’s expected text must be coordinated in the same release; otherwise one version may falsely fail or silently conceal outdated wording.
Changed-context transfer exercise: a library reservation
A public library uses a feature describing a reader reserving a book. The source includes a Scenario Outline with columns <member_type>, <item_status> and <expected_result>. One row verifies that an active member can reserve an available book; another verifies that an expired member cannot reserve it. A translator is asked to provide a target-language feature, but the step definitions accept English sentences, the @reservation tag selects nightly tests, and the result column contains internal status keys. What should be translated, what needs coordinated refactoring, and how can the librarian know the intended access rule survived?
The reader-facing feature title, scenario descriptions and step-body sentences can be translated with the librarian’s approved terminology. The Gherkin keywords must use a supported dialect if a language directive is chosen. The outline placeholders and column headers must remain coordinated; it is safest to preserve technical names unless engineering explicitly updates all references. The @reservation tag and internal result keys should remain untouched because they select and drive tests. If target step text no longer matches definitions, add reviewed language-specific bindings or keep the executable canonical suite while supplying a clearly marked translated reading edition.
To demonstrate success, enumerate both example rows, show the active member’s reservation succeeds, show the expired member’s request is blocked, and inspect the target-language outcome with a librarian. A translation that uses the same word for ‘book available’ and ‘reservation confirmed’ is misleading: availability describes an item state, while confirmation describes a completed action. The exercise transfers the earlier lessons about state, actors, syntax and negative cases to a different service. The answer is not merely ‘translate the English words’ but ‘preserve an observable contract while changing the reading language’.
A practical pre-release inspection
Open the target feature with a bilingual reviewer and trace it from Feature to Rule, Background, each scenario and its examples. Verify that a supported grammar dialect parses the file and that no section has silently disappeared. Confirm that all step bodies either match a reviewed definition or are explicitly labelled as documentation-only. Check placeholder names against example headers, data-table widths, Doc String payload types, literal escape sequences and tags used by tooling. Then inspect the most consequential statements about permissions, negative cases, money, deadlines and final states against the source policy.
For every failed test, retain the failure category. A syntax failure requires grammar or structural repair. An undefined step requires reviewed binding work. A fixture failure requires investigation of expected keys and locale-specific values. A behaviour assertion failure may reveal a real product bug, an incorrect expectation or a translation error. Do not make arbitrary changes until the category is known. A translator who records this distinction can hand off concise evidence to developers and product owners instead of producing a vague request to ‘make the translated file run’.
Finally, store an evidence packet: source commit, target file, approved termbase version, target dialect, scenario inventory, test report, screenshots if relevant and reviewer sign-off. Link the packet to the release branch. The next team can then reproduce the checks instead of trusting an undocumented ‘done’. The process is lightweight for one feature and scales by repeating the same boundaries across many files. Speed comes from reducing uncertainty, not from skipping important verification.
What this approach can and cannot guarantee
The technique preserves a documented behavioural relationship between a .feature file, its steps and an observed system. It does not establish that the source feature correctly describes the underlying business policy, that the test environment represents production or that every untested input is safe. A passing translated test has the same coverage limitations as its source. Where the source is ambiguous or wrong, translators should flag the defect and ask for a product-owner decision; they should not silently ‘improve’ the requirements as part of language work.
Gherkin is also not the correct container for every localisation need. End-user interface labels, notifications, emails, help pages, date formats and accessibility messages are often managed by separate resource systems. A translated feature may assert that a particular message appears in one locale, but changing that application’s translated resources is a distinct change. Keeping these reader jobs separate prevents a Cucumber tutorial from becoming an unbounded manual for the entire product. It also makes the delivered file easier to audit and maintain.
Summary: protect the promise being tested
Fast, reliable Gherkin translation starts with the tested promise, then preserves its grammar, binding, examples and observable result. Choose a supported dialect rather than inventing keywords. Distinguish the business sentence from the technical expression that executes it. Preserve identifiers and test selectors unless the project has a reviewed migration. Most importantly, let product owners judge whether the target-language scenario still communicates the same permission, obligation and result. That is how a feature file becomes useful in more than one language without losing the reason it was written.
Frequently asked questions
Can I translate only Given, When and Then?
You can localise supported grammar keywords, but that alone leaves feature descriptions and step bodies in their source language. It may be useful as a demonstration, not as a complete stakeholder translation.
Why does a translated feature say its steps are undefined?
Cucumber matches step-body text to step definitions. Translating that body changes what must match; use reviewed target-language definitions, shared helper wrappers or a clearly documented canonical-language execution strategy.
Can I translate @smoke into the target language?
Only after checking filters, CI configuration and tooling. Tags often act as technical selectors even though they look like words.
Should scenario outlines change their placeholder names?
Only through a coordinated refactor that also updates example headers and any binding assumptions. A purely linguistic change is not enough.
Are examples safe to translate automatically?
No. They may contain fixed keys, boundary values, test inputs or visible strings. Classify cells before editing them.
What if my target language has several supported keywords?
Use the currently documented Cucumber dialect and adopt one consistent team convention while respecting valid alternatives.
Does a passing Cucumber test prove translation quality?
No. It proves that configured assertions passed for the executed examples. A bilingual domain review must still verify meaning and stakeholder interpretation.
Can feature translation fix a defective original requirement?
It can expose the defect, but the product owner must authorise any change in the tested rule. Record the ambiguity instead of silently rewriting behaviour.
What is the quickest first test for a new locale?
Translate one representative scenario, validate syntax, inspect step matching, execute it in isolation and review its observed outcome with a target-language domain expert.
Should we keep two parallel feature suites forever?
Not automatically. Compare maintenance cost, execution coverage and stakeholder needs. Some teams benefit from multilingual executable suites; others keep one canonical executed suite and a controlled translated reading layer.
Technical sources and further reading
- Cucumber: Gherkin Reference — official grammar, structure, keywords, step matching and scenario outlines.
- Cucumber: Gherkin Localisation — documented supported dialect keywords and language codes.
- Cucumber: Introduction — executable specifications and step-definition model.
- Cucumber Expressions — the maintained expression implementation and parameter concepts; verify against the installed package version.
Relevant eduKateSG reading pathways
- How People Translate Quickly | Drupal Interface Translation QA — a different problem: interface string catalogues instead of executable scenarios.
- How People Translate Quickly | Moodle Language Customisation QA — software locale text and maintained language customisations.
- How People Translate Quickly | Directus Translations Interface QA — locale-aware content relationships, not test bindings.