Install & Compatibility
Where this runs
tested against v0.19.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.060s · 18.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.050s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FluentParser
✓ from fluent.syntax.parser import FluentParser
FluentSerializer
✓ from fluent.syntax.serializer import FluentSerializer
ast
✓ from fluent.syntax import ast
Provides access to AST nodes like Resource, Message, Term, etc.
Visitor
✓ from fluent.syntax.visitor import Visitor
✗ from fluent.syntax.ast import Visitor
The Visitor and Transformer classes were refactored into `fluent.syntax.visitor` from `fluent.syntax.ast` in version 0.18.0.
Transformer
✓ from fluent.syntax.visitor import Transformer
✗ from fluent.syntax.ast import Transformer
The Visitor and Transformer classes were refactored into `fluent.syntax.visitor` from `fluent.syntax.ast` in version 0.18.0.
This quickstart demonstrates parsing a Fluent Translation List (FTL) string into an Abstract Syntax Tree (AST) using `FluentParser` and then serializing the AST back into an FTL string using `FluentSerializer`. This showcases the core functionality of reading and writing Fluent syntax programmatically.
from fluent.syntax.parser import FluentParser
from fluent.syntax.serializer import FluentSerializer
ftl_source = """
# Welcome message
hello = Hello, { $username }!
# Plural example
num-emails = { $num ->
[one] You have one email.
*[other] You have { $num } emails.
}
"""
parser = FluentParser()
resource = parser.parse(ftl_source)
print("--- Parsed AST ---")
# For a more readable AST, you might want to use a custom visitor or ast.dump
# For simplicity, we'll just print the resource object's representation.
print(resource)
serializer = FluentSerializer()
serialized_ftl = serializer.serialize(resource)
print("\n--- Serialized FTL ---")
print(serialized_ftl)
Debug
Known issues
breakingVersion 0.19.0 dropped official support for Python 2.7 and 3.5. Users on these Python versions should remain on `fluent-syntax<0.19.0`.fixUpgrade to Python 3.6 or newer, or pin `fluent-syntax` to `<0.19.0`.
affects: 0.19.0+
breakingIn version 0.18.0, the deprecated `BaseNode.traverse` method was removed. Additionally, `Visitor` and `Transformer` classes were refactored and moved from `fluent.syntax.ast` to `fluent.syntax.visitor`.fixUpdate import paths for `Visitor` and `Transformer` to `from fluent.syntax.visitor import ...`. Replace usages of `BaseNode.traverse` with the `Visitor` or `Transformer` pattern as appropriate.
affects: 0.18.0+
gotchaPrior to version 0.18.1, serializing multiline patterns (especially those starting with special Fluent syntax characters like `[`, `.`, `*`, or `{`) could lead to incorrect output or syntax errors if the pattern elements didn't explicitly force a new line. `FluentSerializer` now correctly handles these cases.fixUpgrade to `fluent-syntax` 0.18.1 or newer. If on an older version, ensure multiline patterns starting with special characters are carefully constructed or manually formatted to avoid serialization issues.
affects: <0.18.1
gotchaWhile `fluent.syntax.visitor.Transformer` allows in-place modification of an AST, care must be taken. Arbitrary modifications can lead to an AST that, when serialized, does not produce valid Fluent content. Always validate the transformed AST if performing complex manipulations.
Errors
Common errors & fixes
SyntaxError: Expected token
This error occurs when the Fluent parser encounters invalid FTL (Fluent Translation List) syntax in the input string, such as missing parentheses, incorrect characters, or malformed messages.
fixReview the FTL string for syntax compliance according to the Fluent specification. Ensure all syntax elements like message IDs, attributes, variants, and placeholders are correctly formed. For example, ensure all parentheses, braces, and quotes are matched and correctly placed.
ModuleNotFoundError: No module named 'fluent_syntax'
This error happens when attempting to import the `fluent-syntax` library using an incorrect module name. The package is typically installed as `fluent-syntax`, but its internal Python package name uses a dot notation, `fluent.syntax`.
fixEnsure the library is installed with `pip install fluent-syntax`. Then, use the correct import statement, usually `from fluent.syntax import parser` or `from fluent.syntax import ast` to access its components.
AttributeError: 'NoneType' object has no attribute 'value'
This error arises when you attempt to access an attribute (like 'value') on an AST node that is `None`. This often happens if the `fluent-syntax` parser fails to find a specific part of a Fluent message (e.g., a message's value or an attribute's value) due to malformed FTL, and subsequent code attempts to access it without checking for `None`.
fixBefore accessing attributes on parsed AST nodes, always check if the node or its sub-components are `None` or if the parsing resulted in `Junk` entries, especially when dealing with potentially invalid FTL. Implement error handling or checks like `if message.value is not None:` before proceeding.
Upgrade
Version history
0.19.0latest on PyPI · released Mar 16, 2023
Audit
Dependencies
No dependency data recorded yet.