Automatic translations update

i18n/translation-templates/AGENTS.pot

@@ -0,0 +1,109 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2018-2026, Slavi Pantaleev, Aine Etke, MDAD community members
+# This file is distributed under the same license as the matrix-docker-ansible-deploy package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: matrix-docker-ansible-deploy \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-18 04:11+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#: ../../../AGENTS.md:7
+msgid "Guidance for AI agents"
+msgstr ""
+
+#: ../../../AGENTS.md:9
+msgid "This file gives AI coding agents the minimum context for working on this repository. Human contributors may find it a useful summary too."
+msgstr ""
+
+#: ../../../AGENTS.md:11
+msgid "What this is"
+msgstr ""
+
+#: ../../../AGENTS.md:13
+msgid "An Ansible playbook that installs and manages a Matrix homeserver and dozens of related services, each running as a Docker container wrapped in a systemd service."
+msgstr ""
+
+#: ../../../AGENTS.md:15
+msgid "Layout"
+msgstr ""
+
+#: ../../../AGENTS.md:17
+msgid "`setup.yml`: the main playbook, listing all roles."
+msgstr ""
+
+#: ../../../AGENTS.md:18
+msgid "`roles/custom/`: roles maintained in this repository."
+msgstr ""
+
+#: ../../../AGENTS.md:19
+msgid "`roles/galaxy/`: external roles, downloaded according to `requirements.yml` via [agru](https://github.com/etkecc/agru) (preferred) or `ansible-galaxy`. Run `just roles` to install them (or `just update` to also pull the playbook itself). Editing these roles locally is fine while preparing or testing a fix, but the changes get wiped on the next roles update, so they must be synced back to the role's upstream repository, followed by a version pin update in `requirements.yml`."
+msgstr ""
+
+#: ../../../AGENTS.md:20
+msgid "`group_vars/matrix_servers`: wires roles together (feeding one role's variables into another). Values a role can construct by itself belong in the role's `defaults/main.yml`, not here."
+msgstr ""
+
+#: ../../../AGENTS.md:21
+msgid "`docs/`: user-facing documentation, one page per component."
+msgstr ""
+
+#: ../../../AGENTS.md:22
+msgid "`i18n/`: translation infrastructure. Do not edit locale files by hand; they are managed by automation."
+msgstr ""
+
+#: ../../../AGENTS.md:23
+msgid "`CHANGELOG.md`: user-facing announcements, newest first."
+msgstr ""
+
+#: ../../../AGENTS.md:25
+msgid "Conventions"
+msgstr ""
+
+#: ../../../AGENTS.md:27
+msgid "Follow the [style guide for playbook developers](docs/style-guide.md). In particular:"
+msgstr ""
+
+#: ../../../AGENTS.md:29
+msgid "Variable prefixes match the role directory name."
+msgstr ""
+
+#: ../../../AGENTS.md:30
+msgid "Playbook-extensible list variables use the `_auto` + `_custom` split; `_custom` is reserved for users."
+msgstr ""
+
+#: ../../../AGENTS.md:31
+msgid "Renamed or removed variables get a validation entry, so stale user configuration produces an error instead of being silently ignored. Each role deprecates its own variables in its `validate_config.yml`; the `matrix_playbook_migration` role covers eliminated roles and very-early validation, and also gates breaking changes via `matrix_playbook_migration_expected_version` (see the style guide)."
+msgstr ""
+
+#: ../../../AGENTS.md:32
+msgid "Every file carries SPDX license headers ([REUSE](https://reuse.software/) specification)."
+msgstr ""
+
+#: ../../../AGENTS.md:33
+msgid "New components must be registered in `setup.yml`, `group_vars/matrix_servers`, `docs/README.md`, `README.md`, `docs/container-images.md`, and get a `CHANGELOG.md` entry."
+msgstr ""
+
+#: ../../../AGENTS.md:35
+msgid "Other notes"
+msgstr ""
+
+#: ../../../AGENTS.md:37
+msgid "Documentation examples use `example.com`, `@alice:example.com`, and the other placeholder values listed in the style guide."
+msgstr ""
+
+#: ../../../AGENTS.md:38
+msgid "Write role tasks concurrency-safe: use `ansible.builtin.tempfile` for temporary files (removed in an `always` block), never fixed shared paths."
+msgstr ""
+
+#: ../../../AGENTS.md:39
+msgid "One logical change per commit."
+msgstr ""

i18n/translation-templates/docs/README.pot

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: matrix-docker-ansible-deploy \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2026-06-29 17:11+0000\n"
+"POT-Creation-Date: 2026-07-18 04:11+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -161,13 +161,17 @@ msgid "[Self-building](self-building.md)"
 msgstr ""
 
 #: ../../../docs/README.md:93
-msgid "[Uninstalling](uninstalling.md)"
+msgid "[Style guide for playbook developers](style-guide.md)"
 msgstr ""
 
 #: ../../../docs/README.md:95
-msgid "[Updating users passwords](updating-users-passwords.md)"
+msgid "[Uninstalling](uninstalling.md)"
 msgstr ""
 
 #: ../../../docs/README.md:97
+msgid "[Updating users passwords](updating-users-passwords.md)"
+msgstr ""
+
+#: ../../../docs/README.md:99
 msgid "[Using Ansible for the playbook](ansible.md)"
 msgstr ""

i18n/translation-templates/docs/style-guide.pot

@@ -0,0 +1,253 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2018-2026, Slavi Pantaleev, Aine Etke, MDAD community members
+# This file is distributed under the same license as the matrix-docker-ansible-deploy package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: matrix-docker-ansible-deploy \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-18 04:11+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#: ../../../docs/style-guide.md:8
+msgid "Style guide for playbook developers"
+msgstr ""
+
+#: ../../../docs/style-guide.md:10
+msgid "This page describes the conventions used when developing this playbook and writing its documentation. Follow it when adding a new component (a role and its documentation page) or editing existing ones, so that everything stays consistent."
+msgstr ""
+
+#: ../../../docs/style-guide.md:12
+msgid "The guide is meant for anyone preparing a contribution, humans and AI agents alike. If you find existing files that deviate from it, feel free to send a pull request bringing them in line."
+msgstr ""
+
+#: ../../../docs/style-guide.md:14
+msgid "Language"
+msgstr ""
+
+#: ../../../docs/style-guide.md:16
+msgid "Write in English, using American spelling (\"customize\", not \"customise\")."
+msgstr ""
+
+#: ../../../docs/style-guide.md:17
+msgid "Proper nouns are capitalized: Matrix, Element, Synapse, Ansible, Docker, Traefik, Postgres, Grafana, etc. Some projects deliberately brand themselves in lowercase (e.g. `baibot`, `rageshake`, `coturn`, `mautrix-telegram`) and keep their lowercase name even at the start of a sentence. When in doubt, follow the upstream project's own spelling."
+msgstr ""
+
+#: ../../../docs/style-guide.md:19
+msgid "Markdown style"
+msgstr ""
+
+#: ../../../docs/style-guide.md:21
+msgid "Do not hard-wrap prose. Each paragraph is a single line in the source file, no matter how long. This keeps the source and the rendered result consistent and makes diffs and translations easier to work with."
+msgstr ""
+
+#: ../../../docs/style-guide.md:22
+msgid "Number ordered lists sequentially (`1.`, `2.`, `3.`), instead of relying on the Markdown renderer to fix a repeated (`1.`, `1.`, `1.`) or wrong (`1.`, `2.`, `4.`) sequence."
+msgstr ""
+
+#: ../../../docs/style-guide.md:23
+msgid "Use `-` for unordered lists."
+msgstr ""
+
+#: ../../../docs/style-guide.md:24
+msgid "Wrap variable names, file paths, commands, domains, and service names in backticks (`` ` ``)."
+msgstr ""
+
+#: ../../../docs/style-guide.md:25
+msgid "Use fenced code blocks with a language hint (```` ```yaml ````, ```` ```sh ````) for configuration and command examples."
+msgstr ""
+
+#: ../../../docs/style-guide.md:26
+msgid "Use relative links when linking between documentation pages (e.g. `[Configuring DNS](configuring-dns.md)`)."
+msgstr ""
+
+#: ../../../docs/style-guide.md:27
+msgid "Link to the upstream project's official documentation instead of duplicating its content (installation steps, distro-specific commands, etc.). Copied instructions go stale; links age much better."
+msgstr ""
+
+#: ../../../docs/style-guide.md:29
+msgid "Example values"
+msgstr ""
+
+#: ../../../docs/style-guide.md:31
+msgid "Use these placeholder values in documentation and code comments, so examples look the same everywhere:"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "What"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "Value"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "base domain"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "`example.com`"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "Matrix server domain"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "`matrix.example.com`"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "another (federated) server"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "`example.org`"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "user IDs"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "`@alice:example.com`, `@bob:example.com`"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "room ID"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "`!qporfwt:example.com`"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "room alias"
+msgstr ""
+
+#: ../../../docs/style-guide.md:0
+msgid "`#room:example.com`"
+msgstr ""
+
+#: ../../../docs/style-guide.md:42
+msgid "The user and room ID values follow the examples in the [Matrix specification](https://spec.matrix.org/latest/#room-structure). Never use real domains, usernames, or tokens in examples."
+msgstr ""
+
+#: ../../../docs/style-guide.md:44
+msgid "Component-specific identifiers (e.g. a bridge bot like `@telegrambot:example.com`) are fine where they make an example clearer."
+msgstr ""
+
+#: ../../../docs/style-guide.md:46
+msgid "Documentation page structure"
+msgstr ""
+
+#: ../../../docs/style-guide.md:48
+msgid "Each component gets its own documentation page: `docs/configuring-playbook-<component>.md` (bridges use a `configuring-playbook-bridge-<name>.md` file name, bots use `configuring-playbook-bot-<name>.md`)."
+msgstr ""
+
+#: ../../../docs/style-guide.md:50
+msgid "A typical page looks like this, with sections appearing in this order (sections that do not apply can be omitted):"
+msgstr ""
+
+#: ../../../docs/style-guide.md:74
+msgid "Notes:"
+msgstr ""
+
+#: ../../../docs/style-guide.md:76
+msgid "Headings use sentence case (\"Adjusting the playbook configuration\", not \"Adjusting The Playbook Configuration\")."
+msgstr ""
+
+#: ../../../docs/style-guide.md:77
+msgid "The \"Adjusting the playbook configuration\" section tells people to add configuration to their `inventory/host_vars/matrix.example.com/vars.yml` file and shows a minimal `yaml` example."
+msgstr ""
+
+#: ../../../docs/style-guide.md:78
+msgid "The \"Installing\" section references [playbook tags](playbook-tags.md) and shows the `just` command or `ansible-playbook` invocation to run."
+msgstr ""
+
+#: ../../../docs/style-guide.md:79
+msgid "Look at an existing page for a similar component (another bridge, bot, or service) and copy its structure. The mautrix bridge pages share common sections via [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md), so bridge pages link there instead of repeating the shared content."
+msgstr ""
+
+#: ../../../docs/style-guide.md:81
+msgid "Adding a new component"
+msgstr ""
+
+#: ../../../docs/style-guide.md:83
+msgid "First, consider where the component belongs:"
+msgstr ""
+
+#: ../../../docs/style-guide.md:85
+msgid "Matrix-specific components are developed as roles in this repository, under `roles/custom/`."
+msgstr ""
+
+#: ../../../docs/style-guide.md:86
+msgid "Components that are not Matrix-specific should live as external roles, preferably in the [MASH organization](https://github.com/mother-of-all-self-hosting/), and get wired into the playbook via `requirements.yml`."
+msgstr ""
+
+#: ../../../docs/style-guide.md:87
+msgid "For components that are not Matrix-specific, also consider whether they belong in this Matrix playbook at all, or rather in [mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook). Certain components (like Grafana or backup tools) are suitable for both playbooks. If something is too far away from general usefulness on a Matrix server, we prefer not to include it here, and to only have it in mash-playbook."
+msgstr ""
+
+#: ../../../docs/style-guide.md:89
+msgid "Besides the role itself and its documentation page, a new component touches a few other places. Make sure a pull request adding one covers all of them:"
+msgstr ""
+
+#: ../../../docs/style-guide.md:91
+msgid "The role, in `roles/custom/matrix-<component>/` (or an external role wired via `requirements.yml`, as described above)."
+msgstr ""
+
+#: ../../../docs/style-guide.md:92
+msgid "Role registration in `setup.yml`."
+msgstr ""
+
+#: ../../../docs/style-guide.md:93
+msgid "Wiring in `group_vars/matrix_servers`. Wire the component to the rest of the playbook there (referencing variables of other roles), but keep values that the role can construct by itself in the role's own `defaults/main.yml`."
+msgstr ""
+
+#: ../../../docs/style-guide.md:94
+msgid "The documentation page, `docs/configuring-playbook-<component>.md`, linked from the table of contents in `docs/README.md`."
+msgstr ""
+
+#: ../../../docs/style-guide.md:95
+msgid "An entry in the supported services list in `README.md`."
+msgstr ""
+
+#: ../../../docs/style-guide.md:96
+msgid "A row in `docs/container-images.md`, if the component runs a container."
+msgstr ""
+
+#: ../../../docs/style-guide.md:97
+msgid "A `CHANGELOG.md` entry announcing the new component."
+msgstr ""
+
+#: ../../../docs/style-guide.md:98
+msgid "License headers: every new file carries `SPDX-FileCopyrightText` and `SPDX-License-Identifier` comments, as this project follows the [REUSE](https://reuse.software/) specification."
+msgstr ""
+
+#: ../../../docs/style-guide.md:100
+msgid "Variable naming conventions:"
+msgstr ""
+
+#: ../../../docs/style-guide.md:102
+msgid "The variable prefix matches the role directory name: the `matrix-bridge-mautrix-telegram` role uses `matrix_bridge_mautrix_telegram_*` variables, the `matrix-bot-mjolnir` role uses `matrix_bot_mjolnir_*` variables, and so on."
+msgstr ""
+
+#: ../../../docs/style-guide.md:103
+msgid "List-type variables that the playbook may extend automatically follow the `_auto` + `_custom` split: the main variable combines an `_auto` component (managed by the playbook via `group_vars`) and a `_custom` component (reserved for users). Where it makes sense, there is also a `_default` component, containing sensible defaults provided by the role itself. See `matrix_bridge_hookshot_container_additional_networks` and `matrix_bridge_hookshot_systemd_required_services_list` for examples."
+msgstr ""
+
+#: ../../../docs/style-guide.md:104
+msgid "When a variable is renamed or removed, deprecate it so that people with stale configuration get told about it instead of it being silently ignored. Each role deprecates its own variables, in its `validate_config.yml` tasks. The `matrix_playbook_migration` role handles the cases a role cannot: variables of completely eliminated roles (which no longer have their own `validate_config.yml`), and validation that needs to run very early for some reason."
+msgstr ""
+
+#: ../../../docs/style-guide.md:105
+msgid "For breaking changes that require the user's attention (beyond a renamed variable that validation already catches), bump `matrix_playbook_migration_expected_version` and add a matching entry to the `matrix_playbook_migration_breaking_changes` list (a summary and a `CHANGELOG.md` link), in `roles/custom/matrix_playbook_migration/defaults/main.yml`. Users declare `matrix_playbook_migration_validated_version` in their configuration, and the playbook walks them through all breaking changes between their validated version and the expected one. Also update the recommended value in `examples/vars.yml`; a pre-commit check enforces that it matches the expected version."
+msgstr ""