GNU FriBidi CLI helps developers and translators investigate bidirectional text in Arabic and Hebrew interfaces. When right-to-left sentences contain English product names, invoice numbers or links, the central requirement is to keep their logical content intact while rendering the mixture in a readable order. A mistaken shortcut can make a screenshot look plausible while damaging the text that readers copy or search.
This practical guide covers the Unicode Bidirectional Algorithm, the fribidi command-line utility, base direction, embedding levels, mixed-script punctuation and real-world RTL localization QA. It explains how to inspect a UTF-8 example without confusing direction ordering with machine translation, character conversion or font shaping.
The safest publication process combines diagnostic tools with native-language review, final-screen testing and integrity checks for machine-readable values. The principles apply to websites, apps, manuals, invoices and public information across countries. No single command can confirm that a translated message is semantically accurate or that every renderer displays it accessibly.
Quick practical answers
Keep source strings in logical order. Test a representative mixed-direction sentence, not only an isolated word. Never reverse identifiers manually. Check copy-paste, keyboard navigation, responsive wrapping, numbers and accessibility. Use the installed fribidi –help output to confirm available diagnostic options.
First command-line test
fribidi --version
fribidi --help
fribidi sample.txtWhat right-to-left localization really changes
Arabic and Hebrew user interfaces must handle words with different writing directions while preserving the same logical data. The central distinction is between the stored sequence of characters and the order in which glyphs appear on a page. Correct localization means making those layers cooperate rather than manually reversing the letters. An Arabic paragraph can contain a Latin brand name, digits and punctuation; each element still needs to be readable and meaningful to its intended reader.
A string that looks correctly aligned can still behave incorrectly. A customer may copy a reference number and get unexpected characters, or a closing parenthesis may seem attached to the wrong part of the sentence. These are not problems solved by replacing vocabulary. They require attention to direction, isolation, layout and sometimes the text renderer itself. The source translation must remain in ordinary logical order.
The most useful starting practice is to preserve the original Unicode string, record the target locale and check the sentence in the actual product. A console program can help narrow down why a mixed-script run appears unusual, but the final result should be judged through a task: reading an instruction, copying an ID, selecting a link or understanding a number.
What GNU FriBidi provides
GNU FriBidi implements the Unicode Bidirectional Algorithm and includes a command-line utility called fribidi. The library computes visual ordering and can provide mappings and embedding levels. The executable is especially useful for inspecting individual examples, comparing input with output and developing regression cases. It is not a translation engine, and its technical output should not be confused with a complete accessibility or typography audit.
Begin by checking fribidi –version and fribidi –help on the machine being used. A simple test is fribidi sample.txt with a short UTF-8 file. Some flags can show details such as base direction and mapping information, but options should be verified against the installed build. Capture both the original file and diagnostic output so another person can reproduce the observation.
Upstream documentation explicitly notes limitations in the command-line tool’s line handling and position mappings. That qualification matters for long text, wrapped mobile cards and editors with complex caret behavior. A successful command execution is evidence about a particular processing step, not proof of how every browser, PDF reader or application will render the string.
Logical text versus a visual screenshot
Unicode logical order generally follows the intended sequence of text, including the internal spelling of an English term embedded in Arabic or Hebrew prose. The visual order is determined for display through bidirectional layout rules. Those two representations should not be collapsed into a single hand-edited string. A visual screenshot is only one presentation under one set of fonts, widths and direction settings.
Consider a Hebrew customer-support sentence containing the Latin identifier INV-2048/A. The identifier should keep exactly the same bytes when stored and copied. If the screenshot shows its punctuation in an awkward position, investigate how the identifier is embedded and which paragraph direction applies. Do not reverse its slash or reorder its characters to imitate a single line on screen.
Copy the rendered text into an independent plain-text editor and compare the character order with the source. This simple check catches defects that screenshot approval misses. For sensitive account numbers, links, serial numbers or file paths, compare exact strings automatically. A reader needs to be able to use the data, not merely admire a line that appears visually plausible.
The meaning of base direction
The paragraph base direction supplies a reference frame for text runs. In some interfaces, it is inferred from the first strongly directional character; in others, the developer should explicitly supply it. This makes an important difference when a translated message begins with a Latin order code or a number before reaching Arabic or Hebrew prose.
Construct two safe test strings containing the same Arabic sentence, one beginning with a simple Latin label and the other beginning with the Arabic words. Compare them under a right-to-left container and an automatic-direction container. If the position of punctuation or the code changes, inspect the paragraph direction and isolation choices before asking a translator to rewrite the sentence.
An unreliable workaround adds a random directional character to the beginning solely to force one screenshot to look right. The fix may fail when the message is abbreviated or the identifier changes. A robust application sets appropriate direction semantics at the component boundary and treats independently inserted content as its own directional unit.
Embedding levels and their usefulness
The Unicode Bidirectional Algorithm assigns embedding levels used in visual reordering. The parity of a level indicates its directional character: even levels correspond to left-to-right treatment and odd levels to right-to-left treatment. This is not a classification of words into translated phrases. It is technical information about how runs of characters relate during rendering.
Suppose a Hebrew sentence contains a product name, a number and an ending colon. If punctuation appears to attach to the wrong element, level information may help reveal which run the renderer associates it with. Combine this with the actual source code points and the paragraph base direction. The exact numeric level alone cannot tell you whether a sentence is idiomatic or whether the amount is correct.
Treat the level listing as a map for debugging, not a format to copy into the translation catalogue. Once a likely issue is identified, test the proposed correction using the real layout engine. Compare the narrow mobile view with a wide desktop view, because line boundaries and surrounding content can affect what appears on screen.
Neutral punctuation and paired symbols
Parentheses, commas, quotation marks, colons and some other symbols have directional behavior influenced by neighbouring characters. In a mixed-script sentence, a closing mark can appear visually distant from the phrase it belongs to. This can happen even when every Arabic, Hebrew and English word is spelled correctly. It is a display-order question before it is a translation question.
Test a complete sentence with a parenthetical software version such as (CloudDesk 4.2), a trailing period and a translated instruction. Do not inspect only the parenthetical phrase. The neighbours determine the relevant context. Then repeat the case with a longer product name and with the text wrapping across two lines. A fix that works for one short case may not generalize.
Never switch opening and closing bracket characters in the stored content simply to make one screenshot attractive. Some paired symbols are mirrored by rendering behavior, and manual substitution can produce the wrong structure elsewhere. For actual code or mathematics, isolating the expression within an appropriately left-to-right container often offers a clearer solution.
Arabic shaping is a separate layer
Arabic script can require contextual glyph shaping. A string may have the correct direction and character order but still appear with disconnected letters in a primitive terminal or unsuitable font. FriBidi’s principal purpose is bidirectional text ordering. Full rendering usually requires additional shaping and font support. Confusing these layers can lead to damaging edits.
Compare the same Arabic sentence in a modern browser and in a plain command-line display. If the visual word order is appropriate but the glyphs are not joined, investigate shaping and font support. Replacing ordinary letters with presentation-form code points to imitate joined shapes is an unsafe shortcut; it may harm search, editing and reuse in other renderers.
Use a font and rendering environment suitable for the language. Test the actual product at normal and enlarged text sizes. When reporting the defect, say whether the issue involves direction, glyph joining, clipping, line wrapping or incorrect linguistic content. Precise classification saves time and keeps translators from being asked to repair software layout with vocabulary changes.
Hebrew vowel points and specialist text
Hebrew content may include niqqud, other combining marks or careful citation conventions. These features matter particularly for educational, religious and scholarly documents. An ordinary unpointed sentence may look fine while a text with combining marks has placement problems. Logical order, font rendering and word meaning each need checking.
Create a representative sentence with pointed Hebrew words and an adjacent Latin citation. View it in the intended font at several sizes and under realistic line spacing. Confirm that marks remain associated with the correct letters and that the citation has an intact, copyable sequence. A command-line visual order display does not settle the font placement question.
A careless attempt to normalize or reverse characters can detach marks from their intended base characters. For high-value specialist text, ask a reviewer familiar with the writing conventions to examine the result. Preserve original code points for comparison rather than relying only on the visible page.
Latin identifiers and links in RTL paragraphs
Software names, error codes, URLs, email addresses and file paths need their own integrity checks. Their internal spelling and punctuation usually must remain unchanged, even when the explanatory language is Arabic or Hebrew. These objects should often be displayed as independent directionally isolated runs within the surrounding paragraph.
Consider an Arabic error message followed by E_CONN_04 and a help link. The translated explanation can change, but the error code should remain an exact key for support diagnostics. Test clicking the link, copying the code and reading it aloud through assistive technology. A visually reversed identifier can be a functional failure even if the rest of the message is understood.
Keep identifiers separate from human-language text in structured resources where possible. Compare placeholders before and after localization. If a business workflow depends on exact data entry, verify that the data copied from the RTL screen matches the canonical value byte for byte.
Inserted names and direction isolation
Template-driven applications insert user names, addresses and tracking values inside translated sentences. Their writing direction is not known in advance. A Hebrew sentence may contain an Arabic name, or an Arabic notice may contain a Latin company and a numerical reference. Without isolation, the inserted content can influence nearby punctuation and adjacent runs.
Test a sample notification with English, Arabic, Hebrew and mixed-script recipient names. Add punctuation immediately after the placeholder, and try the message at short and long widths. The translation may be correct while the container that combines it with user data behaves poorly. These are component-level defects that can affect many strings.
Treat the placeholder as an independent unit whose direction can be handled by the application. Avoid adding invisible marks to every translation in a blind attempt to compensate for missing structural boundaries. The same template should work for a broad set of legitimate names and identifiers.
Accessibility and editing behavior
Right-to-left localization quality includes keyboard selection, cursor navigation, screen reading and text extraction. A visually correct screenshot does not demonstrate that the information works for people using assistive technology or copying data into another application. Logical text and correct language metadata are crucial parts of accessible communication.
Test a multilingual form containing a Hebrew label, English email address and Arabic help text. Move the caret through the input, select portions of the value, copy the result and listen to the message through a screen reader. Observe whether the focus order and speech make sense to someone completing the task, not merely to an engineer examining code.
Do not flatten the language into an image just to avoid bidi issues. That sacrifices searchability, selection, scalable text and meaningful accessibility. Repair the underlying direction and rendering behavior and retain real text in the application.
Build a realistic RTL regression set
A maintainable regression set should cover pure Arabic and Hebrew text, Latin names, numbers, punctuation, placeholders, links, dates, percentages, long labels and line breaks. Include the components people use most often: error messages, invoices, search results, navigation, notifications and form fields. Keep strings synthetic when they represent personal information.
Record the original logical string and an approved result in a real renderer. Test at multiple screen widths, with the fonts actually shipped. When a defect is reported, reduce it to the shortest example that still fails and add it to the regression set. This allows the team to notice when a font, framework or message template change reintroduces a problem.
Separate linguistic review from display testing. A native reader judges whether the translation communicates the intended meaning; the development team verifies that exact identifiers and interface behavior remain functional. A release is ready only when both strands agree that the user can complete the task.
Make the release decision transparent
An automated FriBidi check is a useful diagnostic but should not be advertised as a full localization certificate. A passed command does not demonstrate correct Arabic vocabulary, accurate numbers, accessible navigation or stable PDF extraction. Strong release decisions identify which checks were run, which problems remain and who approved the language.
Keep a simple release note covering text-source integrity, language approval, directional rendering, responsive layout, embedded data and accessibility. When a warning exists, state its user impact. A harmless visual discrepancy and a miscopied transaction identifier require very different responses. This makes the workflow efficient without trivializing consequential errors.
Revisit the regression examples after changes to fonts, component widths, code format or dynamic data. The translations may be unchanged while the behavior surrounding them has altered. Preserve the original source and prior approved examples so the cause can be located and the correction reviewed.
Useful references
The GNU FriBidi project documents the library and its CLI; Unicode Standard Annex #9 defines the bidirectional algorithm. Unicode encoding and transliteration are different problems; see the ICU uconv localization guide for those workflows.
Worked RTL localization examples
Case study: an Arabic delivery notification
Imagine a delivery notice written in Arabic that says a package with reference AB-209/4 is ready for collection. The words around the reference are translated, but the reference is data supplied by a tracking system. It must remain exact and easy to copy. A user might also see the notice in a compact phone notification that cuts the message into two visual lines.
Test the original logical sentence with the code at the beginning, middle and end. Compare the display with explicit RTL paragraph direction and with an isolated LTR code span. Then copy the code from each result and confirm that its characters match the data record. Pay attention to slash, hyphen, final punctuation and any icon positioned near the code.
The lesson is that a direction fix needs to protect an actual task, not merely the appearance of the sentence. If the RTL explanation is understandable but a copied code cannot be used on the carrier’s website, the localization has failed. Record the corrected component pattern so future tracking numbers of different lengths receive the same protection.
Case study: a Hebrew financial statement
A Hebrew bank-facing statement may combine a transaction date, a signed amount, a percent, a currency abbreviation and a Latin merchant reference. This is a higher-risk setting than a decorative headline because a reader needs to understand exactly which amount belongs to which transaction. The bidi algorithm influences display, while financial formatting rules determine the meaning of each numeric field.
Build a synthetic record with a positive charge, a negative adjustment and a refund. Display all three within Hebrew explanations, then compare the exact numeric values against the underlying dataset. Check whether the minus sign, decimal separator and parentheses create an ambiguous visual grouping. Repeat the test on desktop and mobile, because narrow columns intensify these problems.
Do not let the localization process change a number or infer a currency from the surrounding language. Ask a local finance reviewer to approve formatting conventions and a technical reviewer to confirm data integrity. FriBidi can help identify unusual directional behavior, but it cannot establish the legal or financial correctness of a transaction.
Case study: bilingual search results
A search results page may be in Arabic while the indexed documents include English names, Hebrew quotations and numeric filenames. Each result title is independent content. When several result snippets are concatenated without clear directional boundaries, punctuation from one item can appear as though it belongs to its neighbour.
Prepare a test page with at least five results: pure Arabic, a Latin product title, a mixed English-Arabic title, a URL and a title ending in numbers. Ensure each result has its own paragraph or container direction policy. Search for one identifier, open the result and copy the title into another program to compare the text order.
Search indexing should operate on the logical text, not a visually reordered string generated to suit one screen. Otherwise users might see a title they can read but fail to retrieve it using valid source characters. Preserve clean storage, design result containers correctly and validate search with authentic multilingual terms.
Case study: an RTL software error dialog
Technical messages often contain a stable error code and a localized explanation. In an Arabic error dialog, an identifier such as E_AUTH_12 may appear beside a translated instruction to sign in again. The code matters to support staff; the surrounding text matters to the user. Neither should be corrupted by a display workaround.
Keep the error code as a separate data field and render it in a distinct, appropriately isolated span. Test a sentence with the code first, last and in parentheses. Confirm that the dialog remains readable at increased font size and that a screen reader presents the explanatory message and code coherently. Copy the code into a mock support ticket.
If the code changes during a script conversion or directional formatting step, the support workflow can break. If the message reads awkwardly despite correct code presentation, send that issue to linguistic review rather than altering the identifier. Distinguishing data integrity, layout and translation accuracy gives each problem a clear owner.
Case study: a medical appointment reminder
A right-to-left reminder can contain a patient’s preferred name, clinic address, time, date and appointment reference. The patient’s name may not be written in the same script as the message. The medical instructions must still remain unambiguous, particularly where arrival times or preparation requirements are important.
Use invented data in tests to protect privacy. Insert an Arabic name into a Hebrew reminder, then a Latin name into an Arabic reminder. Check how the time, address and punctuation move around the inserted values. Verify that the displayed appointment time comes from the canonical scheduling system rather than from any arbitrary language conversion.
A visually elegant reminder is not enough if a patient could misread the date or destination. Native-language reviewers should evaluate instructions, while technical tests preserve the underlying appointment fields. FriBidi belongs in the diagnostic toolkit, not in the role of deciding which clinical statement is safe to publish.
Case study: an online lesson with Hebrew examples
Educational text can contain pointed Hebrew words, Latin grammatical labels, English explanations and inline citation numbers. Such material puts unusual demands on direction handling because students may need to examine the exact order and attachment of marks. A misplaced vowel point is more than a cosmetic defect in a reading lesson.
Choose a short annotated passage and render it with the publication’s final font. Test ordinary size, enlarged size, mobile width and a printable PDF. Have a competent Hebrew reader verify the relation between base letters and marks. Copy the passage out of the PDF and inspect whether the logical text remains suitable for searching and reusing in notes.
Do not reverse combining mark sequences or substitute presentation glyphs simply to match one screenshot. Keep the authoritative text in logical Unicode order and treat font shaping, bidirectional display and linguistic correctness as separate checks. This approach protects the educational purpose of the material.
Case study: a mixed-language data table
A product dashboard may place Arabic or Hebrew field labels in the first column while the data cells contain Latin serial numbers, measurements and web addresses. Tables are not simply long paragraphs: headers, values and actions have different semantics. Applying one global direction rule without considering the cells can make reading and comparison difficult.
Create a compact table with a localized item name, a decimal measurement, a signed value, an SKU and an external link. Test whether each value reads correctly under its own direction policy. Compare column alignment and reading order with keyboard-only navigation. Confirm that users can copy the SKU without picking up adjacent punctuation.
The safest solution may use RTL layout for the table as a whole while keeping technical data in LTR cells. Do not let the visual order determine the underlying sorting or export behavior. Check that a CSV export preserves fields and logical strings regardless of their appearance in the interface.
Case study: a chat thread with unknown languages
Messages in a customer-support chat may arrive in several languages, sometimes in the same conversation. Unlike a fixed Hebrew interface, the application cannot assume that every message body has the same direction. A message beginning with a Latin order number may differ from one beginning with Arabic text even if both are written by the same user.
Test individual chat bubbles using separate direction rules or a defined auto-direction strategy. Include Arabic, Hebrew, English, numbers only and mixed-script messages. Verify how quoted replies, timestamps and attachment filenames appear. Test copying a complete message and selecting an isolated code within a bubble.
Never force the entire chat transcript into one undifferentiated RTL paragraph. That can cause one user’s content to influence the display of another message. Preserve message boundaries and avoid rewriting what the sender actually typed. Bidi diagnostics help trace the technical behavior, but the goal is a respectful, functional chat interface.
Case study: multilingual subtitles and captions
A subtitle file may contain Arabic speech, an English brand name and numeric timestamps. The timestamps control playback and should not be subjected to textual reordering. The caption text needs correct language meaning, line breaks and visual reading order. These requirements are connected but should be checked with distinct methods.
Test a short synthetic caption segment and preview it over representative footage. Keep timing codes immutable. Inspect line wrapping on a phone and on a large screen, particularly where a caption changes from Arabic to English. Compare the visible text with the stored caption file and test how it is read by assistive technologies when applicable.
An apparently correct line in a terminal may render differently over video because the subtitle engine uses its own font and layout rules. Do not use a hand-reordered sentence as a universal caption master. Maintain the logical text and approve it in the actual target playback environment.
Case study: terminal output and operations logs
Developers reading operational logs often need to match a stable event code to a localized explanatory message. A log line that mixes RTL descriptions and ASCII tokens may be hard to interpret when viewed through a terminal whose shaping and bidi support differ from that of a graphical app. This is a display challenge, not necessarily a defect in the log data.
Keep an event identifier, timestamp and structured fields separate from the human-facing explanation. In a test file, include Arabic explanatory words followed by a code and a server name. Compare raw JSON or another structured export with terminal output. If the terminal looks unusual, view the same data in a trustworthy Unicode-capable editor.
Do not change machine identifiers or record fields to satisfy a particular terminal renderer. Instead improve log presentation or provide a structured viewer. When reporting a bug, supply exact characters, tool versions and display context. That makes diagnostic output actionable and prevents accidental changes to production evidence.
Case study: an address and navigation map
An RTL travel or delivery page can contain localized explanatory text beside street names, postcode-like values and map links. Geographic names may have an officially accepted spelling that differs from a mechanical conversion. The interface must protect routing identifiers while making the directions readable to visitors.
Use synthetic addresses to test a street name written in Arabic, a Latin building code and a link to a map provider. Inspect punctuation between the building number and street label. Check whether the clickable link points to the intended coordinates, and confirm that a copied address retains the actual characters expected by the service.
A localization correction should not invent a different destination or silently adjust a coordinate. Distinguish officially named places, transliteration and screen direction. The language reviewer confirms the wording; the routing test confirms that a user can still reach the right place.
Case study: a mobile form and validation error
A right-to-left form may show Arabic field labels, a Latin email address, a numeric phone field and translated validation errors. The form has multiple independent directions: the screen layout may flow RTL, while an email address and some validation tokens should remain LTR. Errors need to appear next to the correct fields.
Test entering, editing and copying each field using a real keyboard. Trigger an error for an invalid email address and observe whether the colon, code and closing punctuation display together. Repeat after rotating the screen or increasing text size. Listen to the error announcement through a screen reader and verify its association with the input.
Reversing the text of an email address to satisfy visual alignment breaks the user’s task. Better solutions preserve field-specific semantics and use appropriate direction controls at element level. Keep the localized validation sentence separate from the exact value the user entered.
Case study: localization regression during redesign
A previously correct Arabic page can break after a design update that changes button width, font or icon placement. Nothing in the translated resource file may have changed. The culprit can be wrapping, a modified component direction or an embedded Latin value that now sits at the end of a line.
Keep a before-and-after set of approved test strings with representative screenshots and source values. After a redesign, rerun the same messages at desktop and mobile sizes. Compare not only screenshots but selected text, links and screen-reader behavior. When a regression appears, reduce it to the smallest content example and inspect its bidi properties.
This prevents the translation team from being blamed for an application change. It also gives developers a clear route to fixing the component instead of adding ad hoc invisible marks to the content. A sustainable RTL product treats direction as part of design system quality.
Case study: signing off a multilingual release
A release meeting should not reduce right-to-left quality to a single pass or fail label from a command-line tool. The practical evidence includes source integrity, direction behavior, correct numbers, locale-appropriate language and actual task completion. Each of these can fail independently, and each needs an owner.
Review a small set of high-risk user journeys: sign in, read an invoice, copy an error code, open a link, search a term and submit a form. Use Arabic and Hebrew test data, including long words and embedded Latin identifiers. Record any accepted limitation and the steps needed to reproduce it.
Publish only when the remaining defects are understood and proportionate to their impact. FriBidi provides valuable technical evidence about text ordering, but the final assurance comes from preserving meaning and function for the reader. Maintain those test cases for the next product change.
Frequently asked questions
What is the difference between bidi text and translation?
Bidi describes how scripts of different writing directions are displayed. Translation chooses the meaning and wording. One cannot substitute for the other.
Should I put visually reordered text in the translation catalogue?
No. Keep the authored logical order, and let the application apply appropriate direction and shaping at display time.
Will FriBidi fix disconnected Arabic letters?
It helps with directional ordering. Font shaping and glyph joining are separate rendering concerns.
Can I trust a good screenshot?
Use it as one check, but also test copy-paste, raw characters, numeric values, accessibility and responsive wrapping.
Where can I confirm the flags for my version?
Use the installed fribidi –help and upstream documentation. Build and packaging differences matter.
Does this apply to Hebrew learning materials?
Yes. But pointed Hebrew, combining marks and instructional correctness require font inspection and a reviewer familiar with the orthography.