Fluent Agents Review

fluent-agents-review

Quick Reference

Review Scope

Critical Warnings

NEVER approve FTL that uses tab characters for indentation. Tabs are treated as text content, not whitespace. ALWAYS require spaces (U+0020) only.

NEVER approve FTL that omits the default variant (*[other]) in a select expression. The grammar mandates exactly one default variant.

NEVER approve TypeScript that calls bundle.formatPattern() without an errors array in production code. Omitting it causes the app to throw on the first resolution error.

NEVER approve code that accesses terms via getMessage("-brand-name"). Terms are private and ONLY resolved through message references.

NEVER approve FTL that uses ICU MessageFormat syntax ({count, plural, one{...}}). Fluent uses { $count -> [one] ... *[other] ... }.

FTL Syntax Validation Checklist

Whitespace and Indentation

Identifiers

Comments

Select Expressions

Terms

Built-in Functions

API Usage Validation Checklist

Bundle Setup

Message Retrieval and Formatting

Error Handling

React Integration Validation Checklist

Provider Setup

Localized Component

Hook Usage

Common AI Mistake Detection

When reviewing AI-generated Fluent code, ALWAYS check for these patterns:

Review Execution Order

When performing a Fluent code review, ALWAYS follow this sequence:

1. Scan FTL files — whitespace, identifiers, comments, special characters
2. Validate select expressions — default variant, CLDR categories, syntax
3. Check terms — prefix, visibility, argument constraints
4. Check attributes — value-less messages, React attrs mapping
5. Review TypeScript — two-step API, null checks, error handling
6. Review React code — provider setup, Localized props, hook usage
7. Run anti-pattern scan — check all items in references/anti-patterns.md
8. Check for AI mistakes — ICU confusion, wrong variable syntax, missing defaults

Report findings grouped by severity: Critical > High > Medium > Low.

Decision Trees

Is This FTL Valid?

Message starts with letter? ─── NO ──→ INVALID (must start [a-zA-Z])
  │ YES
  ▼
Uses spaces for indent? ─── NO ──→ INVALID (tabs are text, not indent)
  │ YES
  ▼
Select has *[default]? ─── NO ──→ INVALID (default variant mandatory)
  │ YES
  ▼
Term has value (not attr-only)? ─── NO ──→ INVALID (terms MUST have value)
  │ YES
  ▼
Named args are literals? ─── NO ──→ INVALID (no variable refs in named args)
  │ YES
  ▼
VALID FTL

Is This TypeScript Integration Correct?

Uses new FluentResource()? ─── NO ──→ FIX (raw strings not accepted)
  │ YES
  ▼
Checks addResource errors? ─── NO ──→ FIX (log parse errors)
  │ YES
  ▼
Uses getMessage + formatPattern? ─── NO ──→ FIX (no bundle.format())
  │ YES
  ▼
Null-checks msg.value? ─── NO ──→ FIX (value can be null)
  │ YES
  ▼
Passes errors array? ─── NO ──→ FIX (throws without it)
  │ YES
  ▼
CORRECT INTEGRATION

Reference Links

• references/methods.md -- Complete validation checklist organized by area
• references/examples.md -- Review scenarios with good code, bad code, and fixes
• references/anti-patterns.md -- Consolidated list of ALL anti-patterns (16+)

Official Sources

• https://projectfluent.org/fluent/guide/
• https://github.com/projectfluent/fluent.js
• https://github.com/projectfluent/fluent/blob/master/spec/fluent.ebnf