Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
One of the core principles of Fluent is to provide good basis for excellent error fallback and error reporting.
We recognize three level of errors in Fluent:
- Missing Message: happens when the context does not have the Message with an ID
- Syntax Error: happens when Fluent resource contains an incorrect Fluent syntax
- Runtime Error: happens when a Message cannot be resolved due to error in expression resolution
The first pillar is Fluent syntax which is designed to make it easy to write correct syntax, aid tools at helping user in the task, and recover as quickly as possible in case of error.
The second pillar is parser error recovery. Fluent can recover from the beginning of the next entry after an error, so in almost all scenarios, a syntax error causes at most one message to be lost. In the future we believe it'll be important to isolate even more of most common syntax errors and narrow down the recovery to a single expression.
The third pillar is the use of locale fallback chain in place of a single locale translations which allows for a locale fallback strategy which allows higher-level Fluent libraries to react to a missing entity (either just missing or due to a syntax error) by creating a context in the next fallback locale and using a localization from it.
Fourth pillar is the heavy use of syntactic aids for recovery purposes. Not only does the syntax make it possible to recover quickly, but also in case of a runtime error such as a selector not matching any variant, Fluent enforces one of the variants to be marked as default which it can then use at runtime to recover from an error scenario.
Fifth pillar is last resort recovery. Fluent is designed with a focus on the experience of the end user in the error scenario, and the users ability to understand as much of the UI as possible even when all things break down.
For that reason, Fluent recovers from broken expressions by presenting a readable form of the expression it could not resolve, for example a variable ID, or message reference.
In the complete breakage scenario where no value can be resolved out of the Message or when no fallback language contains a missing message, Fluent vision is to make bindings return an ID of the message in place of the value, which is a significant improvement for the user over an empty string most translation systems return.
Additionally, the concept of
compound messages allows Fluent bindings to use one of the user-visible attributes instead of the value for displaying the last-resort message. For example, HTML input localized with Fluent, in case of a missing message, will display the ID as
placeholder instead of as content.
Fluent puts a lot of emphasis on improving user experience of working with translations.
The first level is improving the information retrieved from the parser and helping, both command line, and graphic tools, display readable errors. The error display system in Fluent is shaped after Rust, with ability to show full readable Messages annotated with errors, warnings, notes, hints and other ways to aid user in recovering from the error scenario.
An example of a command line error slice that could come our of the parser or other tool might look like this:
The second level, is working together with the authors of CAT tools to make the parser provide enough information for advanced UI features aiding localizer in his work.
An example of such task is providing a special UI for selecting the right accesskey attribute for a compound message used to translate a menu item:
As part of the effort, Project Fluent aims to deliver a basic set of tools to help localizers and projects in the localization cycle and maintain clean and high quality translation resources over time.
Tools that aid with localization bootstrapping, generating the status of translation, merging translations, formatting Fluent syntax files to their canonical form and others.