Pygments Lexer for Fluent

Common errors

• pygments.util.ClassNotFound: no lexer for alias 'fluent'

  cause The `FluentLexer` is not properly registered or imported when Pygments attempts to find it by alias. This often happens if `fluent-pygments` is not installed or if the Pygments environment isn't aware of the installed lexer.
  fix Ensure `fluent-pygments` is installed (`pip install fluent-pygments`). If using Pygments directly in Python, explicitly import `FluentLexer` and pass it to `highlight()`.

• ModuleNotFoundError: No module named 'fluent_pygments.lexer'

  cause The Python interpreter cannot find the `fluent_pygments.lexer` module. This is typically due to `fluent-pygments` not being installed in the current environment or an incorrect import path.
  fix Install `fluent-pygments` using `pip install fluent-pygments`. Verify the package is in your environment by trying to import it interactively.

• Highlighted HTML output is monochrome or lacks expected styling.

  cause The default `HtmlFormatter` only adds CSS classes to the HTML elements, but does not embed the CSS definitions themselves. Without a linked stylesheet, the browser does not know how to style these classes.
  fix Generate the stylesheet for your chosen Pygments style (e.g., `pygmentize -S default -f html > default.css`) and link this CSS file in your HTML document. Alternatively, set `noclasses=True` on `HtmlFormatter` to embed inline styles, but this makes the HTML larger.

Warnings

• gotcha Pygments' `HtmlFormatter` (by default) generates HTML with CSS classes, but does not embed the actual CSS styles. For fully styled output, a separate CSS file must be generated and linked, or inline styles must be explicitly enabled (though not recommended for larger outputs).
  Fix: Generate a stylesheet using `pygmentize -S <style_name> -f html > style.css` and include it in your HTML, or initialize `HtmlFormatter(noclasses=True)` for inline styles.
• gotcha Processing untrusted or very large Fluent (FTL) input with Pygments can lead to performance issues or potential Denial-of-Service (DoS) attacks if not properly constrained, due to the complexity of regular expression matching in lexers.
  Fix: Implement strict input size limits and/or apply timeouts to the Pygments highlighting process when handling user-provided content. Limit the number of concurrent highlighting processes.
• deprecated The broader `python-fluent` ecosystem, of which `fluent-pygments` is a part, has dropped support for older Python versions (e.g., Python 2.7 and 3.5 in `fluent.runtime` and `fluent.syntax` releases after `fluent-pygments` 1.0). While `fluent-pygments` 1.0 itself requires Python >=3.6, ensure your environment aligns with the latest `fluent.*` components if using them together.
  Fix: Upgrade to Python 3.6 or newer. For best compatibility with the `python-fluent` ecosystem, use Python 3.8+.

Install

• pip install fluent-pygments Install stable version

Imports

• FluentLexer
  wrong:

  from pygments.lexers import FluentLexer

  correct:

  from fluent_pygments.lexer import FluentLexer

  Custom lexers provided by third-party packages are typically imported directly from their package, not from `pygments.lexers`.

Quickstart

This example demonstrates how to use the `FluentLexer` with Pygments to highlight Fluent (FTL) code. It shows how to output the highlighted code both as a complete HTML document and as colored text for a 256-color terminal. The HTML output typically requires a separate CSS stylesheet for proper rendering, which can be generated using `pygmentize -S <style_name> -f html > style.css`.

from pygments import highlight
from pygments.formatters import HtmlFormatter, Terminal256Formatter
from fluent_pygments.lexer import FluentLexer

ftl_code = """
### A resource comment for the whole file
my-key = Localize { -brand-name }
-brand-name = Fluent
# $num is the number of strings to localize
plurals = { $num ->
    [one] One string
   *[other] {$num} strings
}
"""

# Highlight to HTML
html_formatter = HtmlFormatter(full=True, style='default')
highlighted_html = highlight(ftl_code, FluentLexer(), html_formatter)

# To see output, you might write to a file or print the raw HTML
# print(highlighted_html)

# Highlight to terminal with 256 colors
terminal_formatter = Terminal256Formatter(style='monokai')
highlighted_terminal = highlight(ftl_code, FluentLexer(), terminal_formatter)

print("\n--- HTML Output Snippet (not runnable directly) ---\n")
print(highlighted_html[:500] + "...") # Print a snippet for brevity
print("\n--- Terminal Output ---\n")
print(highlighted_terminal)