FTL-Extract 0.0.1__tar.gz

ftl_extract-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ftl_extract-0.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.1
+Name: FTL-Extract
+Version: 0.0.1
+Summary: Extracts FTL files from a directory and outputs them to a directory
+License: MIT
+Keywords: ftl,ftl-extract,ftl-extractor
+Author: andrew000
+Requires-Python: >=3.9
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: fluent-syntax (>=0.19,<0.20)
+Requires-Dist: libcst (>=1.4,<2.0)
+Description-Content-Type: text/markdown
+
+# FTL-Extract
+
+## Description
+
+FTL-Extract is a Python package that extracts Fluent keys from .py files
+and generates a .ftl file with extracted keys.
+
+## Installation
+
+Use the package manager [pip](https://pip.pypa.io/en/stable) to install
+FTL-Extract.
+
+``` bash
+pip install FTL-Extract
+```
+
+## Usage
+
+``` bash
+ftl_extract code_path output_path
+```
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first
+to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.
+

ftl_extract-0.0.1/README.md

@@ -0,0 +1,28 @@
+# FTL-Extract
+
+## Description
+
+FTL-Extract is a Python package that extracts Fluent keys from .py files
+and generates a .ftl file with extracted keys.
+
+## Installation
+
+Use the package manager [pip](https://pip.pypa.io/en/stable) to install
+FTL-Extract.
+
+``` bash
+pip install FTL-Extract
+```
+
+## Usage
+
+``` bash
+ftl_extract code_path output_path
+```
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first
+to discuss what you would like to change.
+
+Please make sure to update tests as appropriate.

ftl_extract-0.0.1/pyproject.toml

@@ -0,0 +1,129 @@
+[tool.poetry]
+name = "FTL-Extract"
+description = "Extracts FTL files from a directory and outputs them to a directory"
+version = "0.0.1"
+authors = ["andrew000"]
+keywords = ["ftl", "ftl-extract", "ftl-extractor"]
+readme = "README.md"
+license = "MIT"
+packages = [
+    { include = "ftl_extract", from = "src" },
+]
+
+[tool.poetry.dependencies]
+python = ">=3.9"
+fluent-syntax = "^0.19"
+libcst = "^1.4"
+
+[tool.poetry.group.test.dependencies]
+pytest = "8.2.2"
+pytest-cov = "5.0.0"
+pytest-html = "4.1.1"
+pytest-mock = "3.14.0"
+coverage = "7.5.4"
+
+[tool.poetry.group.docs.dependencies]
+sphinx = "7.3.7"
+sphinx-rtd-theme = "2.0.0"
+sphinx-autobuild = "2024.4.16"
+furo = "2024.5.6"
+pytz = "2024.1"
+
+[tool.poetry.group.dev.dependencies]
+black = "24.4.2"
+isort = "5.13.2"
+pre-commit = "3.7.1"
+ruff = "0.5.1"
+mypy = "1.10.1"
+typing-extensions = "4.12.2"
+
+[tool.poetry.scripts]
+ftl_extract = "ftl_extract.cli:cli_extract"
+ftl_export = "ftl_export.__main__:main"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = "tests"
+
+[tool.mypy]
+packages = ["src/ftl_extract"]
+exclude = [
+    "\\.?venv",
+    "\\.idea",
+    "\\.tests?",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "def __str__",
+    "if TYPE_CHECKING:",
+    "importlib.metadata",
+]
+
+[tool.isort]
+py_version = 39
+src_paths = ["src", "tests"]
+line_length = 100
+multi_line_output = 3
+force_grid_wrap = 0
+include_trailing_comma = true
+split_on_trailing_comma = false
+single_line_exclusions = ["."]
+sections = ["FUTURE", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"]
+known_first_party = ["ftl_extract"]
+
+[tool.ruff]
+src = ["src", "tests"]
+target-version = "py39"
+line-length = 100
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+    ".venv",
+    "tests/.data_for_testing",
+]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "A003",
+    "ANN002", "ANN003", "ANN101", "ANN102", "ANN401",
+    "COM812",
+    "C901",
+    "D100", "D101", "D102", "D103", "D104", "D105", "D106", "D107", "D203", "D205", "D212",
+    "DTZ003",
+    "ERA001",
+    "F841",
+    "FA100", "FA102",
+    "FBT001", "FBT002",
+    "FIX002",
+    "INP001", "ISC001",
+    "PLR0911", "PLR0912", "PLR0913", "PLR0915", "PLR5501",
+    "PLW0120",
+    "RUF",
+    "S101", "S311",
+    "TD002", "TD003"
+]

ftl_extract-0.0.1/src/ftl_extract/__init__.py

@@ -0,0 +1,4 @@
+from .__version__ import __version__
+from .code_extractor import extract_fluent_keys
+
+__all__ = ("extract_fluent_keys", "__version__")

ftl_extract-0.0.1/src/ftl_extract/__version__.py

@@ -0,0 +1,3 @@
+import importlib.metadata
+
+__version__ = importlib.metadata.version(__package__)

ftl_extract-0.0.1/src/ftl_extract/cli.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ftl_extract.ftl_extractor import extract
+
+
+@click.command()
+@click.argument("code_path", type=click.Path(exists=True, path_type=Path))
+@click.argument("output_path", type=click.Path(path_type=Path))
+@click.option(
+    "--language",
+    "-l",
+    multiple=True,
+    default=("en",),
+    show_default=True,
+    help="Language of translation.",
+)
+@click.option(
+    "--i18n_keys",
+    "-k",
+    default=("i18n", "L", "LazyProxy", "LazyFilter"),
+    multiple=True,
+    show_default=True,
+    help="Names of function that is used to get translation.",
+)
+@click.option(
+    "--beauty",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help="Beautify output FTL files.",
+)
+def cli_extract(
+    code_path: Path,
+    output_path: Path,
+    language: tuple[str, ...],
+    i18n_keys: tuple[str, ...],
+    beauty: bool = False,
+) -> None:
+    click.echo(f"Extracting from {code_path}...")
+
+    extract(
+        code_path=code_path,
+        output_path=output_path,
+        language=language,
+        i18n_keys=i18n_keys,
+        beauty=beauty,
+    )

ftl_extract-0.0.1/src/ftl_extract/code_extractor.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import libcst as cst
+
+from ftl_extract.exceptions import (
+    FTLExtractorDifferentPathsError,
+    FTLExtractorDifferentTranslationError,
+)
+from ftl_extract.matcher import I18nMatcher
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+    from ftl_extract.matcher import FluentKey
+
+
+def find_py_files(path: Path) -> Iterator[Path]:
+    """
+    First step: find all .py files in given path.
+
+    :param path: Path to directory with .py files.
+    :type path: Path
+    :return: Iterator with Path to .py files.
+    :rtype: Iterator[Path]
+    """
+    yield from path.rglob("[!{.}]*.py") if path.is_dir() else [path]
+
+
+def parse_file(path: Path, i18n_keys: str | Sequence[str]) -> dict[str, FluentKey]:
+    """
+    Second step: parse given .py file and find all i18n calls.
+
+    :param path: Path to .py file.
+    :type path: Path
+    :param i18n_keys: Names of function that is used to get translation.
+    :type i18n_keys: str | Sequence[str]
+    :return: Dict with `key` and `FluentKey`.
+    :rtype: dict[str, FluentKey]
+    """
+    module = cst.parse_module(path.read_bytes())
+    matcher = I18nMatcher(code_path=path, func_names=i18n_keys)
+    matcher.extract_matches(module)
+    return matcher.fluent_keys
+
+
+def post_process_fluent_keys(fluent_keys: dict[str, FluentKey]) -> None:
+    """
+    Third step: post-process parsed `FluentKey`.
+
+    :param fluent_keys: Dict with `key` and `FluentKey` that will be post-processed.
+    :type fluent_keys: dict[str, FluentKey]
+    """
+    for fluent_key in fluent_keys.values():
+        if not isinstance(fluent_key.path, Path):
+            fluent_key.path = Path(fluent_key.path)
+
+        if not fluent_key.path.suffix:  # if path looks like directory (no suffix)
+            fluent_key.path /= "_default.ftl"
+
+
+def find_conflicts(
+    current_fluent_keys: dict[str, FluentKey],
+    new_fluent_keys: dict[str, FluentKey],
+) -> None:
+    """
+    Fourth step: find conflicts between current and new `FluentKey`s.
+
+    If conflict is found, raise `ValueError`.
+
+    Conflict is when `key` is the same, but `path` or `kwargs` are different.
+    """
+    # Find common keys
+    conflict_keys = set(current_fluent_keys.keys()) & set(new_fluent_keys.keys())
+
+    if not conflict_keys:
+        return
+
+    for key in conflict_keys:
+        if current_fluent_keys[key].path != new_fluent_keys[key].path:
+            raise FTLExtractorDifferentPathsError(
+                key,
+                current_fluent_keys[key].path,
+                new_fluent_keys[key].path,
+            )
+
+        if not current_fluent_keys[key].translation.equals(new_fluent_keys[key].translation):
+            raise FTLExtractorDifferentTranslationError(
+                key,
+                current_fluent_keys[key].translation,
+                new_fluent_keys[key].translation,
+            )
+
+
+def extract_fluent_keys(path: Path, i18n_keys: str | Sequence[str]) -> dict[str, FluentKey]:
+    """
+    Extract all `FluentKey`s from given path.
+
+    :param path: Path to [.py file] / [directory with .py files].
+    :type path: Path
+    :param i18n_keys: Names of function that is used to get translation.
+    :type i18n_keys: str | Sequence[str]
+    :return: Dict with `key` and `FluentKey`.
+    :rtype: dict[str, FluentKey]
+
+    """
+    fluent_keys: dict[str, FluentKey] = {}
+
+    for file in find_py_files(path):
+        keys = parse_file(file, i18n_keys)
+        post_process_fluent_keys(keys)
+        find_conflicts(fluent_keys, keys)
+        fluent_keys.update(keys)
+
+    return fluent_keys
+
+
+def sort_fluent_keys_by_path(fluent_keys: dict[str, FluentKey]) -> dict[Path, list[FluentKey]]:
+    """
+    Sort `FluentKey`s by their paths.
+
+    :param fluent_keys: Dict with `key` and `FluentKey`.
+    :type fluent_keys: dict[str, FluentKey]
+    :return: Dict with `Path` and list of `FluentKey`.
+    :rtype: dict[Path, list[FluentKey]]
+    """
+    sorted_fluent_keys: dict[Path, list[FluentKey]] = {}
+    for fluent_key in fluent_keys.values():
+        sorted_fluent_keys.setdefault(fluent_key.path, []).append(fluent_key)
+
+    return sorted_fluent_keys

ftl_extract-0.0.1/src/ftl_extract/exceptions.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from fluent.syntax import ast
+
+
+class FTLExtractorError(Exception):
+    pass
+
+
+class FTLExtractorDifferentPathsError(FTLExtractorError):
+    def __init__(self, key: str, current_path: Path, new_path: Path) -> None:
+        self.current_path = current_path
+        self.new_path = new_path
+        super().__init__(
+            f"Key {key!r} already exists with different path: "
+            f"{self.current_path} != {self.new_path}"
+        )
+
+
+class FTLExtractorDifferentTranslationError(FTLExtractorError):
+    def __init__(
+        self,
+        key: str,
+        current_translation: ast.Message | ast.Comment,
+        new_translation: ast.Message | ast.Comment,
+    ) -> None:
+        self.current_translation = current_translation
+        self.new_translation = new_translation
+        super().__init__(
+            f"Translation {key!r} already exists with different elements: "
+            f"{self.current_translation} != {self.new_translation}"
+        )

ftl_extract-0.0.1/src/ftl_extract/ftl_extractor.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from click import echo
+from fluent.syntax import FluentSerializer
+
+from ftl_extract import extract_fluent_keys
+from ftl_extract.code_extractor import sort_fluent_keys_by_path
+from ftl_extract.ftl_importer import import_ftl_from_dir
+from ftl_extract.process.commentator import comment_ftl_key
+from ftl_extract.process.serializer import BeautyFluentSerializer, generate_ftl
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from ftl_extract.matcher import FluentKey
+
+
+def extract(
+    code_path: Path,
+    output_path: Path,
+    language: tuple[str, ...],
+    i18n_keys: tuple[str, ...],
+    beauty: bool = False,
+) -> None:
+    serializer: FluentSerializer | BeautyFluentSerializer
+
+    if beauty is True:
+        serializer = BeautyFluentSerializer(with_junk=True)
+    else:
+        serializer = FluentSerializer(with_junk=True)
+
+    # Extract fluent keys from code
+    in_code_fluent_keys = extract_fluent_keys(code_path, i18n_keys)
+
+    for lang in language:
+        # Import fluent keys from existing FTL files
+        stored_fluent_keys = import_ftl_from_dir(output_path, lang)
+        for fluent_key in stored_fluent_keys.values():
+            fluent_key.path = fluent_key.path.relative_to(output_path / lang)
+
+        keys_to_comment: dict[str, FluentKey] = {}
+        keys_to_add: dict[str, FluentKey] = {}
+
+        # Find keys should be commented
+        # Keys, that are not in code or not in their `path_` file
+        # First step: find keys that have different paths
+        for key, fluent_key in in_code_fluent_keys.items():
+            if key in stored_fluent_keys and fluent_key.path != stored_fluent_keys[key].path:
+                keys_to_comment[key] = stored_fluent_keys.pop(key)
+                keys_to_add[key] = fluent_key
+
+            elif key not in stored_fluent_keys:
+                keys_to_add[key] = fluent_key
+
+            else:
+                stored_fluent_keys[key].code_path = fluent_key.code_path
+
+        # Second step: find keys that are not in code
+        for key in stored_fluent_keys.keys() - in_code_fluent_keys.keys():
+            keys_to_comment[key] = stored_fluent_keys.pop(key)
+
+        for fluent_key in keys_to_comment.values():
+            comment_ftl_key(fluent_key, serializer)
+
+        sorted_fluent_keys = sort_fluent_keys_by_path(stored_fluent_keys)
+
+        for path, keys in sort_fluent_keys_by_path(keys_to_add).items():
+            sorted_fluent_keys.setdefault(path, []).extend(keys)
+
+        for path, keys in sort_fluent_keys_by_path(keys_to_comment).items():
+            sorted_fluent_keys.setdefault(path, []).extend(keys)
+
+        for path, keys in sorted_fluent_keys.items():
+            ftl, _ = generate_ftl(keys, serializer=serializer)
+            (output_path / lang / path).parent.mkdir(parents=True, exist_ok=True)
+            (output_path / lang / path).write_text(ftl, encoding="utf-8")
+            echo(f"File {output_path / lang / path} has been saved. {len(keys)} keys updated.")

ftl_extract-0.0.1/src/ftl_extract/ftl_importer.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fluent.syntax import ast, parse
+
+from ftl_extract.matcher import FluentKey
+
+
+def import_from_ftl(path: Path, locale: str) -> tuple[dict[str, FluentKey], ast.Resource]:
+    """Import `FluentKey`s from FTL."""
+    ftl_keys = {}
+
+    resource = parse(path.read_text(encoding="utf-8"), with_spans=True)
+
+    for entry in resource.body:
+        if isinstance(entry, ast.Message):
+            ftl_keys[entry.id.name] = FluentKey(
+                code_path=Path(),
+                key=entry.id.name,
+                translation=entry,
+                # Cut off the locale from the path
+                path=path,
+                locale=locale,
+            )
+
+    return ftl_keys, resource
+
+
+def import_ftl_from_dir(path: Path, locale: str) -> dict[str, FluentKey]:
+    """Import `FluentKey`s from directory of FTL files."""
+    ftl_files = (path / locale).rglob("*.ftl") if path.is_dir() else [path]
+    ftl_keys = {}
+
+    for ftl_file in ftl_files:
+        keys, _ = import_from_ftl(ftl_file, locale)
+        ftl_keys.update(keys)
+
+    return ftl_keys

ftl_extract-0.0.1/src/ftl_extract/matcher.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable, cast
+
+import libcst as cst
+from fluent.syntax import ast
+from libcst import matchers as m
+
+from ftl_extract.exceptions import (
+    FTLExtractorDifferentPathsError,
+    FTLExtractorDifferentTranslationError,
+)
+
+if TYPE_CHECKING:
+    from typing import Literal
+
+I18N_LITERAL: Literal["i18n"] = "i18n"
+GET_LITERAL: Literal["get"] = "get"
+PATH_LITERAL: Literal["_path"] = "_path"
+
+
+@dataclass
+class FluentKey:
+    """
+    Dataclass for storing information about key and its translation.
+
+    :param code_path: Path to .py file where key was found.
+    :type code_path: Path
+    :param key: Key that will be used to get translation.
+    :type key: str | None
+    :param translation: Translation of key.
+    :type translation: str | None
+    :param path: Path to .ftl file where key will be stored.
+    :type path: Path
+    :param locale: Locale of translation. When extracting from .py file, it will not be needed.
+    :type locale: str | None
+    """
+
+    code_path: Path
+    key: str
+    translation: ast.Message | ast.Comment
+    path: Path = field(default=Path("_default.ftl"))
+    locale: str | None = field(default=None)
+
+
+class I18nMatcher:
+    def __init__(self, code_path: Path, func_names: str | Sequence[str] = I18N_LITERAL) -> None:
+        """
+
+        :param code_path: Path to .py file where visitor will be used.
+        :type code_path: Path
+        :param func_names: Name of function that is used to get translation. Default is "i18n".
+        :type func_names: str | Sequence[str]
+        """
+        self.code_path = code_path
+        self._func_names = {func_names} if isinstance(func_names, str) else set(func_names)
+        self.fluent_keys: dict[str, FluentKey] = {}
+
+        self._matcher = m.OneOf(
+            m.Call(
+                func=m.Attribute(
+                    value=m.OneOf(*map(cast(Callable, m.Name), self._func_names)),
+                    attr=m.SaveMatchedNode(matcher=~m.Name(GET_LITERAL) & m.Name(), name="key"),
+                ),
+                args=[
+                    m.SaveMatchedNode(
+                        matcher=m.ZeroOrMore(
+                            m.Arg(
+                                value=m.DoNotCare(),
+                                keyword=m.Name(),
+                            )
+                        ),
+                        name="kwargs",
+                    )
+                ],
+            ),
+            m.Call(
+                func=m.Attribute(
+                    value=m.OneOf(*map(cast(Callable, m.Name), self._func_names)),
+                    attr=m.Name(value=GET_LITERAL),
+                ),
+                args=[
+                    m.Arg(
+                        value=m.SaveMatchedNode(matcher=m.SimpleString(), name="key"), keyword=None
+                    ),
+                    m.SaveMatchedNode(
+                        matcher=m.ZeroOrMore(
+                            m.Arg(
+                                value=m.DoNotCare(),
+                                keyword=m.Name(),
+                            )
+                        ),
+                        name="kwargs",
+                    ),
+                ],
+            ),
+            m.Call(
+                func=m.OneOf(*map(cast(Callable, m.Name), self._func_names)),
+                args=[
+                    m.Arg(
+                        value=m.SaveMatchedNode(matcher=m.SimpleString(), name="key"), keyword=None
+                    ),
+                    m.SaveMatchedNode(
+                        matcher=m.ZeroOrMore(
+                            m.Arg(
+                                value=m.DoNotCare(),
+                                keyword=m.Name(),
+                            )
+                        ),
+                        name="kwargs",
+                    ),
+                ],
+            ),
+        )
+
+    def extract_matches(self, module: cst.Module) -> None:
+        for match in m.extractall(module, self._matcher):
+            # Key
+            if isinstance(match["key"], cst.Name):
+                key = cast(cst.Name, match["key"]).value
+                translation = ast.Message(
+                    id=ast.Identifier(name=key),
+                    value=ast.Pattern(
+                        elements=[ast.TextElement(value=cast(cst.Name, match["key"]).value)]
+                    ),
+                )
+                fluent_key = FluentKey(code_path=self.code_path, key=key, translation=translation)
+            elif isinstance(match["key"], cst.SimpleString):
+                key = cast(cst.SimpleString, match["key"]).raw_value
+                translation = ast.Message(
+                    id=ast.Identifier(name=key),
+                    value=ast.Pattern(elements=[ast.TextElement(value=key)]),
+                )
+                fluent_key = FluentKey(code_path=self.code_path, key=key, translation=translation)
+            else:
+                msg = f"Unknown type of key: {type(match['key'])} | {match['key']}"
+                raise TypeError(msg)
+
+            # Kwargs
+            for kwarg in cast(Sequence[m.Arg], match["kwargs"]):
+                keyword = cast(cst.Name, kwarg.keyword)
+                if keyword.value == PATH_LITERAL:
+                    fluent_key.path = Path(cast(cst.SimpleString, kwarg.value).raw_value)
+
+                else:
+                    if (
+                        isinstance(fluent_key.translation, ast.Message)
+                        and fluent_key.translation.value is not None
+                    ):
+                        fluent_key.translation.value.elements.append(
+                            ast.Placeable(
+                                expression=ast.VariableReference(
+                                    id=ast.Identifier(name=keyword.value)
+                                )
+                            )
+                        )
+
+            if fluent_key.key in self.fluent_keys:
+                if self.fluent_keys[fluent_key.key].path != fluent_key.path:
+                    raise FTLExtractorDifferentPathsError(
+                        fluent_key.key,
+                        fluent_key.path,
+                        self.fluent_keys[fluent_key.key].path,
+                    )
+
+                if not self.fluent_keys[fluent_key.key].translation.equals(fluent_key.translation):
+                    raise FTLExtractorDifferentTranslationError(
+                        fluent_key.key,
+                        fluent_key.translation,
+                        self.fluent_keys[fluent_key.key].translation,
+                    )
+
+            else:
+                self.fluent_keys[fluent_key.key] = fluent_key

ftl_extract-0.0.1/src/ftl_extract/process/commentator.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fluent.syntax import FluentSerializer, ast
+
+if TYPE_CHECKING:
+    from ftl_extract.matcher import FluentKey
+
+
+def comment_ftl_key(key: FluentKey, serializer: FluentSerializer) -> None:
+    raw_entry = serializer.serialize_entry(key.translation)
+    key.translation = ast.Comment(content=raw_entry.strip())

ftl_extract-0.0.1/src/ftl_extract/process/serializer.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fluent.syntax import FluentSerializer, ast
+from fluent.syntax.serializer import serialize_junk, serialize_message, serialize_term
+
+if TYPE_CHECKING:
+    from fluent.syntax.ast import Resource
+
+    from ftl_extract.matcher import FluentKey
+
+
+class BeautyFluentSerializer(FluentSerializer):
+    """A serializer that formats the output FTL for better readability."""
+
+    def serialize_entry(self, entry: ast.EntryType, state: int = 0) -> str:  # pragma: no cover
+        """Serialize an :class:`.ast.Entry` to a string."""
+        if isinstance(entry, ast.Message):
+            return serialize_message(entry)
+        if isinstance(entry, ast.Term):
+            return serialize_term(entry)
+        if isinstance(entry, ast.Comment):
+            if state & self.HAS_ENTRIES:
+                return "\n{}\n".format(serialize_comment(entry, "#"))
+            return "{}\n".format(serialize_comment(entry, "#"))
+        if isinstance(entry, ast.GroupComment):
+            if state & self.HAS_ENTRIES:
+                return "\n{}\n".format(serialize_comment(entry, "##"))
+            return "{}\n".format(serialize_comment(entry, "##"))
+        if isinstance(entry, ast.ResourceComment):
+            if state & self.HAS_ENTRIES:
+                return "\n{}\n".format(serialize_comment(entry, "###"))
+            return "{}\n".format(serialize_comment(entry, "###"))
+        if isinstance(entry, ast.Junk):
+            return serialize_junk(entry)
+        raise Exception(f"Unknown entry type: {type(entry)}")  # noqa: TRY002, TRY003, EM102
+
+
+def serialize_comment(
+    comment: ast.Comment | ast.GroupComment | ast.ResourceComment,
+    prefix: str = "#",
+) -> str:  # pragma: no cover
+    if not comment.content:
+        return f"{prefix}"
+
+    return "\n".join(
+        [prefix if len(line) == 0 else f"{prefix} {line}" for line in comment.content.split("\n")]
+    )
+
+
+def generate_ftl(
+    fluent_keys: dict[str, FluentKey] | list[FluentKey],
+    serializer: FluentSerializer,
+) -> tuple[str, Resource]:
+    """Generate FTL translations from `fluent_keys`."""
+    resource = ast.Resource(body=None)
+
+    if isinstance(fluent_keys, list):
+        for fluent_key in fluent_keys:
+            resource.body.append(fluent_key.translation)
+    else:
+        for fluent_key in fluent_keys.values():
+            resource.body.append(fluent_key.translation)
+
+    return serializer.serialize(resource), resource