name: update languages
        entry: uv run ./scripts/docs.py update-languages
        files: ^docs/.*|scripts/docs\.py$
        pass_filenames: false

      - id: ensure-non-translated
        language: unsupported
        name: ensure non-translated files are not modified
        entry: uv run ./scripts/docs.py ensure-non-translated
        files: ^docs/(?!en/).*|^scripts/docs\.py$
        pass_filenames: false

### Brief System Overview

The top-level scripts and utility scripts should be fairly well-documented. Here
is a brief explanation of how they tie together:

1.  `envs/*` are lists of variables made with bash syntax. A user must set a
    `TFCI` env param pointing to a list of `env` files.
2.  `utilities/setup.sh`, initialized by all top-level scripts, reads and sets
    values from those `TFCI` paths.

#
# Common setup for all TF scripts.
#
# Make as FEW changes to this file as possible. It should not contain utility
# functions (except for tfrun); use dedicated scripts instead and reference them
# specifically. Use your best judgment to keep the scripts in this directory
# lean and easy to follow. When in doubt, remember that for CI scripts, "keep it
# simple" is MUCH more important than "don't repeat yourself."

            }

            steps {
                script {
                    name = "CHECK_USED_WRAPPER"
                    scriptContent =
                        """
                        set -eu
                        "$defaultJavaBinary" .teamcity/scripts/FindCommits.java ${model.branch.branchName} | \
                        "$defaultJavaBinary" .teamcity/scripts/CheckWrapper.java
                        """.trimIndent()

        run: uv sync --locked --no-dev --group docs
      - name: Update Languages
        run: uv run ./scripts/docs.py update-languages
      - uses: actions/cache@v5
        with:
          key: mkdocs-cards-${{ matrix.lang }}-${{ github.ref }}
          path: docs/${{ matrix.lang }}/.cache
      - name: Build Docs
        run: uv run ./scripts/docs.py build-lang ${{ matrix.lang }}
      - uses: actions/upload-artifact@v7
        with:

      - name: Export Language Codes
        id: show-langs
        run: |
          echo "langs=$(uv run ./scripts/translate.py llm-translatable-json)" >> $GITHUB_OUTPUT
          echo "commands=$(uv run ./scripts/translate.py commands-json)" >> $GITHUB_OUTPUT
        env:
          LANGUAGE: ${{ github.event.inputs.language }}
          COMMAND: ${{ github.event.inputs.command }}

      - name: Deploy Docs Status Error
        if: failure()
        run: uv run ./scripts/deploy_docs_status.py
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          COMMIT_SHA: ${{ github.event.workflow_run.head_sha }}
          RUN_ID: ${{ github.run_id }}
          STATE: "error"
      - name: Comment Deploy
        run: uv run ./scripts/deploy_docs_status.py
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

```

</div>

### Docs Structure

The documentation uses [MkDocs](https://www.mkdocs.org/).

And there are extra tools/scripts in place to handle translations in `./scripts/docs.py`.

/// tip

You don't need to see the code in `./scripts/docs.py`, you just use it in the command line.

///

All the documentation is in Markdown format in the directory `./docs/en/`.

# LLM test file { #llm-test-file }

This document tests if the <abbr title="Large Language Model">LLM</abbr>, which translates the documentation, understands the `general_prompt` in `scripts/translate.py` and the language specific prompt in `docs/{language code}/llm-prompt.md`. The language specific prompt is appended to `general_prompt`.

Tests added here will be seen by all designers of language specific prompts.

Use as follows:

from pathlib import Path

import pytest
from typer.testing import CliRunner

from scripts.translation_fixer import cli

data_path = Path(
    "scripts/tests/test_translation_fixer/test_complex_doc/data"
).absolute()


@pytest.mark.parametrize(
    "copy_test_files",
    [(f"{data_path}/en_doc.md", f"{data_path}/translated_doc.md")],
    indirect=True,
)
def test_fix(runner: CliRunner, root_dir: Path, copy_test_files):