repository·main·Indexed 23 days ago
https://github.com/projectfluent/fluentA localization system designed to handle natural language complexities in translations. This repository provides the specification and reference implementation for the Fluent Syntax (FTL), which supports features such as gender, plurals, and conjugations. It includes a parser-combinator architecture, a CLI tool for parsing FTL files into JSON ASTs, and a tool to generate EBNF from grammar.js. While this is the reference implementation, official production implementations are available for JavaScript (fluent.js), Python (python-fluent), and Rust (fluent-rs).
Fluent is a localization system designed to leverage the expressive power of natural language.
FTL (Fluent Translation List) is the specific syntax used to describe translation resources within Project Fluent. It allows for complex, natural-sounding translations that go beyond simple key-value pairs.
fluent.ebnf file within the repository. For a detailed explanation of how to write and structure FTL files, refer to the official Fluent Syntax Guide.Terms are special identifiers used to define vocabulary and glossary items that can be reused consistently across a product.
Key characteristics:
- (e.g., -brand-name).-brand-name = Firefox
about = About { -brand-name }.
update-successful = { -brand-name } has been updated.Fluent defines three types of changes that affect how translation files are parsed and authored:
SyntaxError).In Fluent, placeables are small pieces of programmable interface denoted by curly braces { and }. They allow you to inject dynamic content into translations at runtime.
There are two primary ways to use placeables:
$ prefix (e.g., { $variableName }) to interpolate values provided by the developer at runtime. These are ideal for user-specific data like names or titles.- prefix (e.g., { -term-name }) to interpolate the value of another message or term defined within the Fluent files.// Using a variable
remove-bookmark = Really remove { $title }?
// Using a term reference
-brand-name = Firefox
installing = Installing { -brand-name }.While most Fluent translations can be written as regular text without delimiters, quoted text (delimited by double quotes) is used to insert characters that have special meaning in Fluent's syntax.
Common use cases for quoted text include:
{ and } are used for placeables, use {"{"} or {"}"} to include literal braces.{" "} at the start of a message to prevent Fluent from stripping leading blanks..), star (*), or bracket ([), Fluent may interpret it as an attribute or variant. Wrap these characters in quoted text within a placeable (e.g., {"["}) to treat them as literal text.Note: Quoted text cannot contain interpolations/placeables itself; it is treated as a literal string when interpolated into regular text via the {"..."} syntax.
opening-brace = This message features an opening curly brace: {"{"}.
closing-brace = This message features a closing curly brace: {"}"}.
blank-is-removed = This message starts with no blanks.
blank-is-preserved = {" "}This message starts with 4 spaces.
leading-bracket =
This message has an opening square bracket
at the beginning of the third line:
{"["}.
attribute-how-to =
To add an attribute to this messages, write
{".attr = Value"} on a new line.
.attr = An actual attribute (not part of the text value above)The Resource node is the root of the AST. It contains the parsed content of the file and includes the original source string for error reporting purposes.
Key properties:
type: Always 'Resource'.body: An array of Entry nodes.comment: The top-level comment, if any.source: The original source string.In Fluent, the fundamental building block is a message. A message is a container used to identify, store, and recall translation information.
Each message consists of:
hello) used by developers to bind the message to a specific location in the software.Hello, world!).In its simplest form, a message is defined by an identifier, an equals sign (=), and a text value. The value begins at the first non-blank character after the = sign.
hello = Hello, world!Fluent uses a specific format called FTL (Fluent Syntax) to describe localization resources. FTL is designed to be human-readable while providing the expressive power necessary to handle complex natural language features such as:
Fluent distinguishes between two levels of correctness for resources:
Why this matters: Some Fluent implementations might skip the semantic validation step for performance reasons. If you are using an implementation that only checks for well-formedness, you should validate your Fluent resources as a separate build-time or compile-time step to ensure they are semantically valid.
A future 2.0 release is intended to break backward compatibility with the 1.x series. The primary purpose of 2.0 is to remove the deprecations accumulated during the 1.x lifecycle.
Goals of the 2.0 transition: