The @axe-core/cli accessibility testing command helps international website teams find detectable WCAG and ARIA problems in translated pages before release. This guide explains how to run axe-core CLI, review HTML language and accessible-name checks, save and triage results, and combine automated accessibility scans with human localization quality assurance. It is intended for developers, translators, content teams and web QA specialists responsible for real multilingual user journeys.
Install the maintained @axe-core/cli package rather than the deprecated axe-cli package, prepare a compatible browser and driver, then audit a target-language page with a command such as axe https://example.org/fr/. Record the tool version, tested URL, browser, locale and page state. The tool can detect many technical accessibility failures, but it does not measure whether a translated promise, label or warning has the right meaning.
For multilingual WCAG testing, the central question is whether the semantic page presented to assistive technology still matches what readers need to do. Learn how to interpret violations, incomplete results and checks that need manual judgment; test both source and target languages; and keep release evidence that survives later content and code changes.
- Primary package: @axe-core/cli, based on the axe-core accessibility engine
- Example: npm install -g @axe-core/cli; axe https://example.org/fr/
- Review detected HTML language, ARIA, forms, landmarks, contrasts and structural findings
- Use rule and tag filtering thoughtfully; never call a filtered pass full conformance
- Save issue evidence with version, browser, locale, reproduction and user consequence
- Pair scans with human translation review, keyboard navigation and actual screen-reader use
Start with the question the reader actually needs answered
Set up the command in a controlled development environment. The maintained package is published as @axe-core/cli; the earlier axe-cli repository is deprecated. The official CLI documentation explains browser and driver requirements, the basic axe URL invocation, and options for rules, tags and output. Use a local or staging page where possible, with explicit permission to run automated tests. A login-protected or dynamic page may need a broader automation harness rather than assuming a raw URL scan sees every state.
For an international release, select test pages from distinct templates: an editorial article, a search page, a transaction form, a details view, a help page and a modal-rich application view. Run a source-language baseline followed by each key target locale, using the same component state. Store the command, versions and output alongside the release build. Avoid attributing every failure to translators; many arise from shared HTML or JavaScript components. Also avoid interpreting a zero-violation scan as a complete review.
What the tool can establish — and where human judgment begins
axe-core is an accessibility testing engine. According to its project documentation, automated checks can identify a significant share of detectable problems, but a portion of criteria require human evaluation and some elements may be returned as incomplete. Results can include violations, passes, incomplete observations and inapplicable checks. These categories are not a grade for translation accuracy. The presence of an html lang attribute does not prove the declared code matches the actual text, and a nonempty accessible name does not mean the name instructs the user correctly.
The standalone command is useful for quick page checks; it is not a multilingual site crawler. The official CLI supports URL execution and controls such as rules and tags; larger suites can integrate axe-core through browser automation or component tests. A practical team decides whether to scan pre-rendered HTML, logged-in views or stateful controls after interaction, and documents what was not tested. High-consequence forms, consent flows, payments and safety messages should also be checked through the keyboard and a screen reader.
Set up a reliable testing environment
Verify Node.js, npm and the installed @axe-core/cli version. Ensure the browser and WebDriver arrangement required by that release functions before debugging localized content. Start with a simple public fixture and run axe against a single URL. If browser startup fails, collect infrastructure logs; do not file an accessibility regression. For selected rule investigations, the official examples include –rules and –tags. For a broader review, use the appropriate unfiltered ruleset and clearly note any exclusions.
Keep the HTML sample deliberately small and representative: a document with a real primary language, an inline translated quotation, a form with an error, a dismissible dialog, a table and an image. Scan it before and after an intentional correction. Learn the difference between an element failing a rule and the full user journey failing. Then extend to production templates, reviewing not just the number of violations but their type, affected elements, locales and consequence.
Choose meaningful pages and rule coverage
Not all pages deserve the same sample size. Start where people make decisions or depend on language to interpret the interface, and make the tool’s coverage explicit.
Verify the primary document language
An English university site publishes a French admissions route under /fr/ with a translated navigation header. Run axe on the French URL and inspect html language results and the actual rendered root element. This check is best treated as a user-facing question rather than an isolated technical rule. An accessibility report becomes valuable when a team can explain who is affected, where the issue occurs and what the translated interface asks that person to do. Begin with the actual page state and identify whether the text was written in the source language, translated in a resource file or generated by a component.
Likely problem: The root still declares en and automated checks may or may not catch the mismatch between a valid code and actual language. Correction route: Set the root to the appropriate language code and separately verify it against the French content. When you investigate the result, preserve the page or component version and the specific locale. A static scan may catch a genuine defect without proving the entire task works. Bring the evidence back to a fluent language reviewer and to a person who can evaluate keyboard or assistive-technology navigation. Their work answers different questions and should not be presented as interchangeable.
Evidence to retain: The final HTML, screen-reader voice behaviour and editorial language specification agree. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Mark embedded language changes
A German research report quotes an Italian legal sentence inside an otherwise German paragraph. Inspect the inline quotation and compare language markup with the actual language boundaries. A useful automated test has a carefully defined scope. Select the translated page, record the environment and decide which region or interaction state represents the user’s real experience. Do not merely run a scanner once on the home page and extrapolate its findings across a large multilingual site. A release can include hundreds of different content patterns and runtime states.
Likely problem: An automated tool cannot reliably judge every inline language change or confirm the quotation’s translation policy. Correction route: Mark the appropriate span and test the quote through a screen reader with supported voices. Separate the technical signal from the editorial interpretation. A missing relationship, invalid attribute or incorrect document language may be straightforward to detect, while an awkward consent sentence or an inaccurate translation requires human judgment. Explain both the detected condition and the task it threatens, then assign the correction to the appropriate owner.
Evidence to retain: A fluent reviewer identifies the language switch and the audible phrase remains understandable. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Detect duplicate IDs in localized templates
A right-to-left registration page repeats an input section when the user selects multiple family members. Scan the expanded form state and inspect element IDs linked to labels and error messages. Think of this scenario as a regression candidate. A good case has a stable fixture, a documented locale, a specific failure condition and a success criterion that does not depend on where a screenshot was taken. That matters because translations change length and layout, and software components change independently from the text they display.
Likely problem: A copied ID makes a label or error describe the wrong family member’s field. Correction route: Generate stable unique IDs and preserve the correct programmatic label relationship. Review any apparent fix on the original language too. If the same shared widget serves ten locales, changing its semantics can repair one and harm another. Prioritize reliable accessible names and states over clever DOM adjustments designed solely to silence a rule. A clean report is a useful milestone, not the product’s real-world endpoint.
Evidence to retain: Each repeated field is named and errors refer to the right person. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Choose WCAG tag filters honestly
A team runs an axe command with one WCAG tag and calls the site fully accessible after a pass. Compare a focused tag run with an unfiltered scan and document which rules were excluded. The reason to record this case is not to collect a larger issue count. It is to make the international product more understandable and safer to operate. Write down what a person could misunderstand, fail to discover or activate by mistake, and whether the consequence is reversible. Those details help a mixed team of writers, engineers and accessibility reviewers agree on severity.
Likely problem: The narrow report leaves out serious issues from other applicable criteria. Correction route: Use targeted runs for investigation and a defined broader evaluation for release readiness. Look closely at changes that do not produce obvious syntax errors: language fallback, inconsistent descriptions, focus movement and delayed messages often survive superficial review. Keep the test repeatable and compare the same route on more than one relevant browser or device when a platform difference could change the answer.
Evidence to retain: The record says precisely which rules or tags were applied and what remains untested. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Protect browser and driver reproducibility
A test runner starts failing after its installed browser silently updates. Reproduce the test on a known fixture and record CLI, browser and driver versions. This check is best treated as a user-facing question rather than an isolated technical rule. An accessibility report becomes valuable when a team can explain who is affected, where the issue occurs and what the translated interface asks that person to do. Begin with the actual page state and identify whether the text was written in the source language, translated in a resource file or generated by a component.
Likely problem: Startup or timeouts are misreported as defects in translated content. Correction route: Repair the execution environment before evaluating new page results. When you investigate the result, preserve the page or component version and the specific locale. A static scan may catch a genuine defect without proving the entire task works. Bring the evidence back to a fluent language reviewer and to a person who can evaluate keyboard or assistive-technology navigation. Their work answers different questions and should not be presented as interchangeable.
Evidence to retain: The same fixture runs consistently and real page findings can be interpreted. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Forms, labels and accessible names
A scanner can expose a missing relationship, but people still have to decide whether the localized words give the correct instruction.
Find unlabeled input fields
A Spanish tax form uses an example placeholder where a persistent account number label should appear. Run the target form and inspect reported label or accessible-name issues. A useful automated test has a carefully defined scope. Select the translated page, record the environment and decide which region or interaction state represents the user’s real experience. Do not merely run a scanner once on the home page and extrapolate its findings across a large multilingual site. A release can include hundreds of different content patterns and runtime states.
Likely problem: The field may be flagged as unnamed, or have a generic name unrelated to its purpose. Correction route: Add a programmatically associated localized label while keeping any example separate. Separate the technical signal from the editorial interpretation. A missing relationship, invalid attribute or incorrect document language may be straightforward to detect, while an awkward consent sentence or an inaccurate translation requires human judgment. Explain both the detected condition and the task it threatens, then assign the correction to the appropriate owner.
Evidence to retain: Keyboard and screen-reader users can identify the required account number field. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Review misleading nonempty names
A translated purchase button has a technically valid accessible name that says ‘Request refund’. Use axe to confirm structural checks and then compare the name with the actual button action. Think of this scenario as a regression candidate. A good case has a stable fixture, a documented locale, a specific failure condition and a success criterion that does not depend on where a screenshot was taken. That matters because translations change length and layout, and software components change independently from the text they display.
Likely problem: Automated rules pass because the name exists, while the dangerous semantic reversal remains undetected. Correction route: Correct the translation and verify the action with a fluent reviewer and assistive technology. Review any apparent fix on the original language too. If the same shared widget serves ten locales, changing its semantics can repair one and harm another. Prioritize reliable accessible names and states over clever DOM adjustments designed solely to silence a rule. A clean report is a useful milestone, not the product’s real-world endpoint.
Evidence to retain: The name accurately describes the action and a tester can predict the consequence. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Preserve grouped field context
A booking page offers several radio options for departure terminal with short repeated labels. Inspect fieldset, legend or equivalent group semantics and navigate the options independently. The reason to record this case is not to collect a larger issue count. It is to make the international product more understandable and safer to operate. Write down what a person could misunderstand, fail to discover or activate by mistake, and whether the consequence is reversible. Those details help a mixed team of writers, engineers and accessibility reviewers agree on severity.
Likely problem: An option is technically labeled but the relevant question is not communicated. Correction route: Provide meaningful group context and concise localized choices. Look closely at changes that do not produce obvious syntax errors: language fallback, inconsistent descriptions, focus movement and delayed messages often survive superficial review. Keep the test repeatable and compare the same route on more than one relevant browser or device when a platform difference could change the answer.
Evidence to retain: A reader knows which selection each radio choice answers. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Make validation errors visible to technology
An application form returns an incorrect postcode warning only through red text. Scan the error state and inspect its programmatic relationship to the field. This check is best treated as a user-facing question rather than an isolated technical rule. An accessibility report becomes valuable when a team can explain who is affected, where the issue occurs and what the translated interface asks that person to do. Begin with the actual page state and identify whether the text was written in the source language, translated in a resource file or generated by a component.
Likely problem: The page may have valid initial markup but produce a disconnected error when validation runs. Correction route: Associate the error with the correct input and announce important changes appropriately. When you investigate the result, preserve the page or component version and the specific locale. A static scan may catch a genuine defect without proving the entire task works. Bring the evidence back to a fluent language reviewer and to a person who can evaluate keyboard or assistive-technology navigation. Their work answers different questions and should not be presented as interchangeable.
Evidence to retain: A user can discover the precise problem and correct it with the keyboard. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Keep icon actions distinct
A multilingual dashboard has three icon-only buttons with identical accessible names. Scan the action toolbar and inspect the reported name issues, then manually evaluate the words. A useful automated test has a carefully defined scope. Select the translated page, record the environment and decide which region or interaction state represents the user’s real experience. Do not merely run a scanner once on the home page and extrapolate its findings across a large multilingual site. A release can include hundreds of different content patterns and runtime states.
Likely problem: A rule can confirm that names are present but not that three identical names are helpful. Correction route: Give each action a specific name such as Download, Remove or View history in the target language. Separate the technical signal from the editorial interpretation. A missing relationship, invalid attribute or incorrect document language may be straightforward to detect, while an awkward consent sentence or an inaccurate translation requires human judgment. Explain both the detected condition and the task it threatens, then assign the correction to the appropriate owner.
Evidence to retain: Each control can be distinguished when navigated without surrounding visual context. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
ARIA, dialogs and dynamic interfaces
Modern localized applications use client-side updates. The scan must observe the relevant state, not only the initial page load.
Check invalid ARIA relationships
A translated FAQ uses an accordion where aria-controls points to an old panel ID after localization. Open and close the accordion and inspect the rendered accessibility attributes. Think of this scenario as a regression candidate. A good case has a stable fixture, a documented locale, a specific failure condition and a success criterion that does not depend on where a screenshot was taken. That matters because translations change length and layout, and software components change independently from the text they display.
Likely problem: A control may expose incorrect associations even though the visible animation works. Correction route: Repair IDs and expanded-state semantics in the shared component. Review any apparent fix on the original language too. If the same shared widget serves ten locales, changing its semantics can repair one and harm another. Prioritize reliable accessible names and states over clever DOM adjustments designed solely to silence a rule. A clean report is a useful milestone, not the product’s real-world endpoint.
Evidence to retain: The controlled panel and announced state match the activated question. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Capture modal dialog state
A payment page opens a translated confirmation dialog only after pressing Continue. Run the relevant accessibility check after the dialog opens, using an appropriate automation harness if needed. The reason to record this case is not to collect a larger issue count. It is to make the international product more understandable and safer to operate. Write down what a person could misunderstand, fail to discover or activate by mistake, and whether the consequence is reversible. Those details help a mixed team of writers, engineers and accessibility reviewers agree on severity.
Likely problem: A simple CLI scan at initial load never sees the modal or its missing name. Correction route: Include the open-dialog state in testing and fix focus containment and accessible naming. Look closely at changes that do not produce obvious syntax errors: language fallback, inconsistent descriptions, focus movement and delayed messages often survive superficial review. Keep the test repeatable and compare the same route on more than one relevant browser or device when a platform difference could change the answer.
Evidence to retain: A screen-reader user can understand and exit the dialog without focus leakage. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Handle live status messages
A translated upload interface changes from Sending to Received without a page navigation. Trigger completion and test announcement behaviour manually alongside static rule checks. This check is best treated as a user-facing question rather than an isolated technical rule. An accessibility report becomes valuable when a team can explain who is affected, where the issue occurs and what the translated interface asks that person to do. Begin with the actual page state and identify whether the text was written in the source language, translated in a resource file or generated by a component.
Likely problem: A scan may report no violations while a screen reader never hears completion. Correction route: Provide a suitable live status mechanism and clear localized confirmation. When you investigate the result, preserve the page or component version and the specific locale. A static scan may catch a genuine defect without proving the entire task works. Bring the evidence back to a fluent language reviewer and to a person who can evaluate keyboard or assistive-technology navigation. Their work answers different questions and should not be presented as interchangeable.
Evidence to retain: A user knows the upload succeeded and does not submit twice. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Avoid contradictory hidden content
A pricing widget hides a detailed explanation visually after the user selects Basic. Inspect the accessibility tree and exposed DOM states for hidden or inert content. A useful automated test has a carefully defined scope. Select the translated page, record the environment and decide which region or interaction state represents the user’s real experience. Do not merely run a scanner once on the home page and extrapolate its findings across a large multilingual site. A release can include hundreds of different content patterns and runtime states.
Likely problem: The screen reader may still encounter an obsolete Premium condition that contradicts the current choice. Correction route: Ensure semantic hidden states follow the active selection and preserve meaningful context. Separate the technical signal from the editorial interpretation. A missing relationship, invalid attribute or incorrect document language may be straightforward to detect, while an awkward consent sentence or an inaccurate translation requires human judgment. Explain both the detected condition and the task it threatens, then assign the correction to the appropriate owner.
Evidence to retain: Only relevant terms are announced for the selected plan. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Retest stateful menus
A language menu dynamically populates options when a user opens the account panel. Inspect the expanded menu, focus movement and names in the open state. Think of this scenario as a regression candidate. A good case has a stable fixture, a documented locale, a specific failure condition and a success criterion that does not depend on where a screenshot was taken. That matters because translations change length and layout, and software components change independently from the text they display.
Likely problem: The initial page passes but dynamically inserted labels are empty or duplicated. Correction route: Fix the interactive component and include the expanded state in regression tests. Review any apparent fix on the original language too. If the same shared widget serves ten locales, changing its semantics can repair one and harm another. Prioritize reliable accessible names and states over clever DOM adjustments designed solely to silence a rule. A clean report is a useful milestone, not the product’s real-world endpoint.
Evidence to retain: A user can choose the intended language without trial and error. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Structures, tables and page navigation
Logical order and correct structure make localized content navigable. Automated findings can reveal important symptoms, but human reading confirms the information architecture.
Inspect heading order and meaning
An English documentation page becomes a Portuguese guide with styled bold text in place of section headings. Scan for related structural findings and navigate headings with a screen reader. The reason to record this case is not to collect a larger issue count. It is to make the international product more understandable and safer to operate. Write down what a person could misunderstand, fail to discover or activate by mistake, and whether the consequence is reversible. Those details help a mixed team of writers, engineers and accessibility reviewers agree on severity.
Likely problem: A visual hierarchy looks intact while assistive navigation lacks the troubleshooting section. Correction route: Use real heading elements and translate headings to be useful when heard alone. Look closely at changes that do not produce obvious syntax errors: language fallback, inconsistent descriptions, focus movement and delayed messages often survive superficial review. Keep the test repeatable and compare the same route on more than one relevant browser or device when a platform difference could change the answer.
Evidence to retain: A reader can navigate to a specific answer via the headings list. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Name landmark regions meaningfully
A multilingual portal contains global navigation, topics navigation and an account menu. Audit landmarks and inspect each region’s accessible name. This check is best treated as a user-facing question rather than an isolated technical rule. An accessibility report becomes valuable when a team can explain who is affected, where the issue occurs and what the translated interface asks that person to do. Begin with the actual page state and identify whether the text was written in the source language, translated in a resource file or generated by a component.
Likely problem: Several navigation landmarks share indistinguishable labels even if their basic roles are valid. Correction route: Give multiple regions distinctive, accurate localized labels. When you investigate the result, preserve the page or component version and the specific locale. A static scan may catch a genuine defect without proving the entire task works. Bring the evidence back to a fluent language reviewer and to a person who can evaluate keyboard or assistive-technology navigation. Their work answers different questions and should not be presented as interchangeable.
Evidence to retain: A reader can jump directly to the intended area. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Associate data-table cells with headers
A comparison table shows shipping prices by region and service type. Scan the table and test row-column navigation with a screen reader. A useful automated test has a carefully defined scope. Select the translated page, record the environment and decide which region or interaction state represents the user’s real experience. Do not merely run a scanner once on the home page and extrapolate its findings across a large multilingual site. A release can include hundreds of different content patterns and runtime states.
Likely problem: A price may be spoken without its destination or service class. Correction route: Correct header and scope relationships rather than converting data to visual-only cards. Separate the technical signal from the editorial interpretation. A missing relationship, invalid attribute or incorrect document language may be straightforward to detect, while an awkward consent sentence or an inaccurate translation requires human judgment. Explain both the detected condition and the task it threatens, then assign the correction to the appropriate owner.
Evidence to retain: The listener can identify each charge and its applicable service. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Provide meaningful image alternatives
An emergency preparedness page includes a flowchart with a translated visible caption. Run an image-alternative check and compare the supplied text with the information the flowchart carries. Think of this scenario as a regression candidate. A good case has a stable fixture, a documented locale, a specific failure condition and a success criterion that does not depend on where a screenshot was taken. That matters because translations change length and layout, and software components change independently from the text they display.
Likely problem: A generic alt such as ‘diagram’ passes a presence check yet communicates no action. Correction route: Write an equivalent purpose-based description or put the steps into readable text nearby. Review any apparent fix on the original language too. If the same shared widget serves ten locales, changing its semantics can repair one and harm another. Prioritize reliable accessible names and states over clever DOM adjustments designed solely to silence a rule. A clean report is a useful milestone, not the product’s real-world endpoint.
Evidence to retain: The same safety sequence is available without seeing the chart. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Preserve navigation after translated expansion
A German help site introduces longer menu text that wraps into additional rows. Scan the resulting page and test the keyboard sequence from header to main content. The reason to record this case is not to collect a larger issue count. It is to make the international product more understandable and safer to operate. Write down what a person could misunderstand, fail to discover or activate by mistake, and whether the consequence is reversible. Those details help a mixed team of writers, engineers and accessibility reviewers agree on severity.
Likely problem: The CSS layout changes but focus order does not align with the apparent workflow. Correction route: Repair DOM or focus order and keep skip-navigation destinations valid. Look closely at changes that do not produce obvious syntax errors: language fallback, inconsistent descriptions, focus movement and delayed messages often survive superficial review. Keep the test repeatable and compare the same route on more than one relevant browser or device when a platform difference could change the answer.
Evidence to retain: A keyboard user can find the main answer without walking every menu item. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Visual contrast, resizing and regional content
Translation changes the shapes and lengths of text. Some risks are detectable; others require testing at different sizes and language combinations.
Verify text contrast in actual states
A localized mobile checkout uses pale grey placeholder text and subtle selected states. Run colour-contrast checks on accessible rendered states and manually inspect changing controls. This check is best treated as a user-facing question rather than an isolated technical rule. An accessibility report becomes valuable when a team can explain who is affected, where the issue occurs and what the translated interface asks that person to do. Begin with the actual page state and identify whether the text was written in the source language, translated in a resource file or generated by a component.
Likely problem: The target language appears correct but text becomes illegible over a shaded background. Correction route: Adjust design tokens and text presentation without modifying the meaning of copy. When you investigate the result, preserve the page or component version and the specific locale. A static scan may catch a genuine defect without proving the entire task works. Bring the evidence back to a fluent language reviewer and to a person who can evaluate keyboard or assistive-technology navigation. Their work answers different questions and should not be presented as interchangeable.
Evidence to retain: Normal and focus states meet the relevant chosen accessibility criteria. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Review long translated links
An Arabic help article has a highly specific link that wraps across multiple lines. Inspect link text and layout at narrow widths alongside the audit output. A useful automated test has a carefully defined scope. Select the translated page, record the environment and decide which region or interaction state represents the user’s real experience. Do not merely run a scanner once on the home page and extrapolate its findings across a large multilingual site. A release can include hundreds of different content patterns and runtime states.
Likely problem: The link is visually clipped or becomes ambiguous through editorial shortening. Correction route: Allow reflow and keep the action-specific accessible name intact. Separate the technical signal from the editorial interpretation. A missing relationship, invalid attribute or incorrect document language may be straightforward to detect, while an awkward consent sentence or an inaccurate translation requires human judgment. Explain both the detected condition and the task it threatens, then assign the correction to the appropriate owner.
Evidence to retain: The link remains readable, focusable and descriptive at supported widths. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Check regional number formatting
A Portuguese pricing page uses local grouping separators in a subscription total. Run the scan and separately inspect rendered totals and accessibility announcements. Think of this scenario as a regression candidate. A good case has a stable fixture, a documented locale, a specific failure condition and a success criterion that does not depend on where a screenshot was taken. That matters because translations change length and layout, and software components change independently from the text they display.
Likely problem: Technical checks pass while the localized amount or billing interval is wrong. Correction route: Fix number formatting and verify the stored value independently from the displayed string. Review any apparent fix on the original language too. If the same shared widget serves ten locales, changing its semantics can repair one and harm another. Prioritize reliable accessible names and states over clever DOM adjustments designed solely to silence a rule. A clean report is a useful milestone, not the product’s real-world endpoint.
Evidence to retain: The charged amount, spoken value and receipt agree. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Check error contrast and specificity
A translated form communicates errors only through a border colour and a tiny warning icon. Scan error states, inspect contrast and manually ask what the user must change. The reason to record this case is not to collect a larger issue count. It is to make the international product more understandable and safer to operate. Write down what a person could misunderstand, fail to discover or activate by mistake, and whether the consequence is reversible. Those details help a mixed team of writers, engineers and accessibility reviewers agree on severity.
Likely problem: The styling may be detected but the underlying textual instruction still lacks a specific solution. Correction route: Add meaningful error text and programmatic associations before adjusting appearance. Look closely at changes that do not produce obvious syntax errors: language fallback, inconsistent descriptions, focus movement and delayed messages often survive superficial review. Keep the test repeatable and compare the same route on more than one relevant browser or device when a platform difference could change the answer.
Evidence to retain: The user recognizes the error without colour and completes the correction. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Inspect right-to-left component states
A navigation panel mirrors layout for Arabic but leaves some icons and numeric data reversed. Audit semantic attributes and navigate the RTL page with a keyboard and screen reader. This check is best treated as a user-facing question rather than an isolated technical rule. An accessibility report becomes valuable when a team can explain who is affected, where the issue occurs and what the translated interface asks that person to do. Begin with the actual page state and identify whether the text was written in the source language, translated in a resource file or generated by a component.
Likely problem: Static rules cannot reliably infer every semantic direction problem or wrong icon meaning. Correction route: Use correct directionality and approved icon mirroring while isolating numeric identifiers. When you investigate the result, preserve the page or component version and the specific locale. A static scan may catch a genuine defect without proving the entire task works. Bring the evidence back to a fluent language reviewer and to a person who can evaluate keyboard or assistive-technology navigation. Their work answers different questions and should not be presented as interchangeable.
Evidence to retain: Numbers, action meaning and navigation order remain accurate. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Evidence, regression and release controls
Turn findings into maintainable tests. International coverage grows when teams can repeat an evaluation after each content or component release.
Store JSON findings responsibly
An engineering team saves axe output from a localized staging site as build evidence. Keep structured results with URL, locale, rule IDs, timestamp, tool version and build identifier. A useful automated test has a carefully defined scope. Select the translated page, record the environment and decide which region or interaction state represents the user’s real experience. Do not merely run a scanner once on the home page and extrapolate its findings across a large multilingual site. A release can include hundreds of different content patterns and runtime states.
Likely problem: Reports are overwritten, mixed across locales or contain confidential account information. Correction route: Use stable file naming, redaction and restricted access where required. Separate the technical signal from the editorial interpretation. A missing relationship, invalid attribute or incorrect document language may be straightforward to detect, while an awkward consent sentence or an inaccurate translation requires human judgment. Explain both the detected condition and the task it threatens, then assign the correction to the appropriate owner.
Evidence to retain: An independent reviewer can reproduce the relevant finding without personal data. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Separate incomplete from passed
A rule returns a result requiring human review rather than a definitive violation. Read the result category and explain its limitation in the release note. Think of this scenario as a regression candidate. A good case has a stable fixture, a documented locale, a specific failure condition and a success criterion that does not depend on where a screenshot was taken. That matters because translations change length and layout, and software components change independently from the text they display.
Likely problem: The team treats inconclusive elements as proven accessible or discards them as noise. Correction route: Assign manual evaluation to the relevant human reviewer and record the conclusion. Review any apparent fix on the original language too. If the same shared widget serves ten locales, changing its semantics can repair one and harm another. Prioritize reliable accessible names and states over clever DOM adjustments designed solely to silence a rule. A clean report is a useful milestone, not the product’s real-world endpoint.
Evidence to retain: Each unresolved case has a clear disposition and evidence. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Prevent blanket exclusions
A shared header produces an unwanted result and someone suggests disabling the entire ruleset. Inspect the affected nodes and compare the user impact with the cost of a targeted correction. The reason to record this case is not to collect a larger issue count. It is to make the international product more understandable and safer to operate. Write down what a person could misunderstand, fail to discover or activate by mistake, and whether the consequence is reversible. Those details help a mixed team of writers, engineers and accessibility reviewers agree on severity.
Likely problem: Removing a broad rule hides unrelated accessibility failures on translated pages. Correction route: Fix the actual component or use a narrowly documented temporary exception only when justified. Look closely at changes that do not produce obvious syntax errors: language fallback, inconsistent descriptions, focus movement and delayed messages often survive superficial review. Keep the test repeatable and compare the same route on more than one relevant browser or device when a platform difference could change the answer.
Evidence to retain: The release record identifies the exception’s scope, owner and expiry. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Add representative locale fixtures
A component library is tested only in English even though it ships Arabic, Japanese and German versions. Create a stable fixture with long strings, mixed scripts, complex labels and deliberate errors. This check is best treated as a user-facing question rather than an isolated technical rule. An accessibility report becomes valuable when a team can explain who is affected, where the issue occurs and what the translated interface asks that person to do. Begin with the actual page state and identify whether the text was written in the source language, translated in a resource file or generated by a component.
Likely problem: New translations break controls long after the original component test passed. Correction route: Integrate locale-specific fixtures into component checks and manual review. When you investigate the result, preserve the page or component version and the specific locale. A static scan may catch a genuine defect without proving the entire task works. Bring the evidence back to a fluent language reviewer and to a person who can evaluate keyboard or assistive-technology navigation. Their work answers different questions and should not be presented as interchangeable.
Evidence to retain: The shared component’s regression set catches repeatable international failures. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
Escalate high-consequence findings
A consent form passes most automated checks but a critical acknowledgement button is inaccessible. Reproduce the failure and document the risk in the actual decision flow. A useful automated test has a carefully defined scope. Select the translated page, record the environment and decide which region or interaction state represents the user’s real experience. Do not merely run a scanner once on the home page and extrapolate its findings across a large multilingual site. A release can include hundreds of different content patterns and runtime states.
Likely problem: Teams prioritize raw issue counts and leave a dangerous action unresolved. Correction route: Set severity according to consequence, ownership and release policy rather than report volume. Separate the technical signal from the editorial interpretation. A missing relationship, invalid attribute or incorrect document language may be straightforward to detect, while an awkward consent sentence or an inaccurate translation requires human judgment. Explain both the detected condition and the task it threatens, then assign the correction to the appropriate owner.
Evidence to retain: The action is usable and its meaning verified before the feature is released. If the result differs across languages, inspect the actual strings, markup and runtime configuration before declaring one layer responsible. Record both the observed outcome and what a user should be able to do without sight, so the final retest checks meaningful behaviour rather than only a vanished diagnostic.
A worked release workflow: from finding to a verified correction
Imagine a multilingual service page whose French search form has a visible label but no programmatic association. First run the CLI against a stable source page and the matching French page. Save the finding, the affected element and the exact URL. Have a reviewer confirm that the field must be labelled ‘Search services’ rather than a misleading generic word. The developer then fixes the form’s accessible association in the shared component, while the translator confirms the final string and context.
Run the same automated check again, then enter the form through keyboard navigation and a screen reader. Listen for the translated name, role and any required state. Trigger a search with no results, because an accessible empty-state announcement is part of the task. Check that the result is neither silent nor falsely presented as success. Repeat in English to ensure that the shared change did not harm the baseline. This pairs technical detection with actual comprehension.
Store the completed evidence under the release version, assign any remaining findings and record any incomplete checks as unresolved rather than silently passed. If a library upgrade changes the output format, compare normalized rule IDs and affected elements instead of ranking releases by raw totals alone. Reuse the same search fixture in the next locale, but change its text and test data enough to expose direction, length and formatting problems. That is the practical value of a stable international QA system.
How to read and prioritize the resulting evidence
Do not group all findings under a single label such as ‘translation issue’. Separate a semantic program failure, a missing accessible name, inaccurate content, an incomplete translation, a device-specific speech difference, and an environmental test failure. Each follows a different repair path. A form field missing its label requires an interface correction; a valid label saying the wrong thing needs editorial correction; a browser process failing to launch needs test infrastructure repair. Mixing them makes progress hard to measure and wastes review time.
Deduplicate carefully, using a reproducible element or journey rather than a raw text search. A shared footer issue on twenty pages may need one component fix but still require checks on representative templates. Conversely, two visually identical warnings may have different underlying causes: one could lack language markup, while another might be mistranslated or absent from the accessibility tree. Keep both distinctions in the record. Capture the actual issue, its affected locales, a suitable owner, the intended user consequence and the result after repair.
Schedule regression checks around real changes: adding a locale, upgrading a component library, changing a content-management template, introducing a new checkout state, or replacing a translation memory entry. Keep test data free of personal information, and use stable sample pages that include accented characters, complex scripts, longer labels, missing-field errors and language fallback. The goal is to protect user journeys throughout a product’s lifetime, not to generate a ceremonial compliance score at launch.
Frequently asked questions
Is a passing automated scan equivalent to WCAG conformance?
No. Automated scanners can identify many detectable failures, but language quality, logical navigation, understandable instructions, focus handling in complex states and real task completion require additional manual checks. A ‘zero issues found’ report is not evidence that every criterion was evaluated or that every reader can use the page.
Why should we review the source language too?
A translated page may inherit inaccessible controls from the underlying component. Without a baseline, teams may blame localization for the wrong cause. Compare source and target builds with matching content states, and then document whether a defect is inherited or newly introduced.
What counts as a useful issue record?
Include a stable URL or view, locale, browser or runtime, exact steps, automated rule or observation, affected element, user consequence, recommended fix, owner and acceptance result. Include a precise excerpt where needed, without exposing private user data.
Do the tools validate translation meaning?
No. A tool may flag missing language metadata, invalid roles or absent labels; it cannot decide whether the word ‘cancel’ was mistranslated as ‘confirm’. A fluent reviewer must evaluate meaning, tone, sensitive instructions, legal terms and cultural conventions.
How do we decide which failures matter most?
Consider both probability and severity. An inaccessible deletion action, missing consent context, payment error or emergency instruction deserves urgent action. Minor formatting issues still need resolution, but severity should be grounded in the harm to a real user journey rather than in raw counts.
How many languages should be sampled?
Start with every target language on critical journeys, then widen the regression matrix according to language diversity, readership and product risk. Include long strings, right-to-left text, complex scripts and regional formats. Sampling is a risk-management method, not proof that untested locales are correct.
What should a release team do after a fix?
Repeat the exact failing check, validate the target language with a competent reviewer, and retest the surrounding workflow using keyboard and assistive technology. Confirm that source-language behaviour and shared components remain intact.
How long should audit evidence be kept?
Retain it according to the project’s privacy, compliance and change-control requirements. At minimum keep the tool version, build, route, locale, findings and verification outcome long enough to explain why a release decision was made. Avoid storing personal form data in logs.
Which package should I install: axe-cli or @axe-core/cli?
Use the maintained @axe-core/cli package. The original dequelabs/axe-cli repository is marked deprecated and points users to the newer package. Check the current CLI README for supported browser, WebDriver and output options.
Can axe-core itself judge the meaning of an accessible name?
It can test certain name-related rules and whether names exist, but it does not establish whether a translated name means the correct action. A semantically wrong yet present label requires a human review and often a real screen-reader task.
Documentation and connected reading
@axe-core/cli official README · axe-core project documentation · W3C WCAG 2.2 · WAI evaluating web accessibility. Consult current project documentation and your chosen accessibility standard when changing command options, rule sets or release policy. Versions, supported browsers and runner behaviour evolve; the examples here describe a review approach, not a promise that every installation is identical.
The next practical step
Select one meaningful localized task, fix a stable test environment and capture the first reproducible result. Connect the detected technical issue to the sentence, control, state or action it changes for a real reader. After correction, ask a fluent reviewer to assess the message and an assistive-technology user to complete the journey. For complementary reading, see NVDA multilingual screen-reader testing and VoiceOver Mac localization QA. The automated and human evidence should reinforce each other, never be confused.