CHANGELOG.md

@@ -22,6 +22,7 @@ Each release lists its changes in these groups, in this order:
 
 ### Added
 
+- `english-comments.yml`, a reusable workflow that judges the language of the comments and docstrings a pull request adds, fails the run when one is not English and writes one comment on the pull request that mentions the author (ADR-0012), with the scripts `tools/english_comments.py` and `tools/english_comments_report.py`, the guide `guides/english-comments.md` and wiki pages in three languages. The scanner of `tools/count_loc.py` can return the text of the comments it finds.
 - `actions/connect-wireguard`, a composite action that brings a WireGuard tunnel up on a Gitea Actions runner for a deployment, with the guide `guides/vpn-wireguard.md`. Experimental.
 - `actions/connect-tailscale`, a composite action for Gitea Actions that joins a Tailscale network for a deployment (the Gitea counterpart of the marketplace action `tailscale/github-action`), with the guide `guides/vpn-tailscale.md`. Experimental.
 

README.md

@@ -17,11 +17,11 @@ A collection of reusable Gitea Actions workflows for DevOps professionals and so
 
 This repository is the central collection of reusable automation for TirSystem repositories. The primary repository lives at `git.tirsystem.com` (Gitea) and is push-mirrored to GitHub.
 
-It contains ten workflows: metadata sync to the GitHub mirror, wiki publishing (called by each repository), shared quality checks for Python and shell, for C and C++ and for C#, code metrics and coverage badges, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#-workflows).
+It contains eleven workflows: metadata sync to the GitHub mirror, wiki publishing (called by each repository), shared quality checks for Python and shell, for C and C++ and for C#, code metrics and coverage badges, a check that comments are in English, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#-workflows).
 
 ## 🔧 Workflows
 
-Ten workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
+Eleven workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
 
 | Workflow | File | Kind | Starts on | Purpose |
 | --- | --- | --- | --- | --- |
@@ -31,6 +31,7 @@ Ten workflows live in this repository. A **scoped** workflow is delivered by the
 | Quality checks C++ | [`quality-checks-cpp.yml`](.gitea/workflows/quality-checks-cpp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs clang-format and clang-tidy at exact versions on the tracked C and C++ files and changes nothing |
 | Quality checks C# | [`quality-checks-csharp.yml`](.gitea/workflows/quality-checks-csharp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs `dotnet format` and `dotnet build` on an exact .NET SDK 10 or later and changes nothing |
 | Code metrics | [`code-metrics.yml`](.gitea/workflows/code-metrics.yml) | Reusable (`workflow_call`) | a call from another repository | Counts the code files and the lines of code (without comment and blank lines), reads a Cobertura coverage report and commits three SVG badges to a `badges` branch |
+| English comments | [`english-comments.yml`](.gitea/workflows/english-comments.yml) | Reusable (`workflow_call`) | a call from another repository, on a pull request | Judges the language of the comments and docstrings a pull request adds, fails the run when one is not English and writes one comment on the pull request that mentions the author |
 | Publish own wiki | [`publish-own-wiki.yml`](.gitea/workflows/publish-own-wiki.yml) | This repository only | push to `main` that changes `docs/wiki/**`, manual | Calls the reusable Publish wiki pages workflow for the wiki of this repository |
 | Release | [`release.yml`](.gitea/workflows/release.yml) | This repository only | manual | Creates the version tag, the release page and the major tag after the checks |
 | Publish accepted milestones | [`sync-milestones.yml`](.gitea/workflows/sync-milestones.yml) | This repository only | push to `main` that changes `docs/milestones/**` or `docs/sqa/reviews/**`, manual (dry run by default) | Creates or updates the Gitea milestone and issues of every milestone that is Accepted with a Go review |
@@ -282,6 +283,46 @@ deactivate Workflow
 @enduml
 ```
 
+### 🔤 English comments
+
+A reusable workflow that checks that the comments and docstrings a pull request adds are written in English, fails the run when one is not, and writes one comment on the pull request that mentions the author. It changes no file and sends no source text outside the instance; marking the check as required in the branch protection is what blocks the merge ([guide](guides/english-comments.md), ADR-0012).
+
+#### 🔀 Workflow
+
+```plantuml
+@startuml
+title English comments check (reusable workflow)
+
+autonumber
+
+actor "Pull request
+uses: ...english-comments.yml@v2" as Caller
+participant "Gitea Actions
+english-comments" as Workflow
+participant "Gitea REST API" as Gitea
+
+Caller -> Workflow: workflow_call with scope, exclude,
+allowed-words-file, threshold and min-words
+activate Workflow
+
+Workflow -> Workflow: Check out the full history and the shared scripts
+Workflow -> Workflow: Install the pinned language detector
+Workflow -> Workflow: Read the comments on the added lines
+Workflow -> Workflow: Remove paths, options, identifiers and allowed words
+Workflow -> Workflow: Judge the language of each comment block
+
+alt a block is not English
+  Workflow -> Gitea: Create or update one comment that mentions the author
+  Workflow --> Caller: run failed (the required check blocks the merge)
+else all blocks are English
+  Workflow -> Gitea: Mark an earlier comment resolved
+  Workflow --> Caller: run passed
+end
+
+deactivate Workflow
+@enduml
+```
+
 ### 🏷️ Release
 
 Started by hand by a maintainer; with `dry_run` `true` (the default) it only checks (see the [release process](guides/release-process.md)).
@@ -546,6 +587,7 @@ Rows that say Implemented or Guides written exist today. The rest is planned and
 | Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adopted in RepoFoundry ([guide](guides/quality-checks.md)) |
 | Shared quality checks (C and C++, C#) | Implemented as the reusable workflows `.gitea/workflows/quality-checks-cpp.yml` and `.gitea/workflows/quality-checks-csharp.yml` with exact tool versions and offline tests; not yet used in another repository (MIL-007) ([C and C++ guide](guides/quality-checks-cpp.md), [C# guide](guides/quality-checks-csharp.md)) |
 | Code metrics and coverage badges | Implemented and released in 2.1.0 as the reusable workflow `.gitea/workflows/code-metrics.yml` with a counter, a Cobertura reader, an SVG renderer and offline tests; tried in a throwaway repository, not yet used in a project repository (MIL-010) ([guide](guides/code-metrics.md)) |
+| English comments | Implemented as the reusable workflow `.gitea/workflows/english-comments.yml` with a comment extractor, a language detector measured on a corpus (ADR-0012), a pull request comment and offline tests; not yet run on the instance or required by any repository (MIL-013) ([guide](guides/english-comments.md)) |
 | Versioned release and publishing | Release process, changelog and upgrade guide defined; the release workflow exists and `v1.0.0` is released (MIL-004) ([guide](guides/upgrading.md)) |
 
 ## 📄 License

docs/wiki/Capabilities.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Capabilities.md, source sha256 3e3bcd9498f7 -->
+<!-- translation of Capabilities.md, source sha256 a8c14f722a77 -->
 
 > Dette er en oversættelse af [`Capabilities`](Capabilities). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -17,4 +17,5 @@ Rækker, der siger Implementeret eller Vejledninger er skrevet, findes i dag. Re
 | Fælles kvalitetskontrol (Python og shell) | Implementeret som det genbrugelige workflow `.gitea/workflows/quality-checks.yml`, med offline-tests og et forsøg i en anden organisation; taget i brug i RepoFoundry ([vejledning](QualityChecksPythonShell.da)) |
 | Fælles kvalitetskontrol (C og C++, C#) | Implementeret som de genbrugelige workflows `.gitea/workflows/quality-checks-cpp.yml` og `.gitea/workflows/quality-checks-csharp.yml` med præcise værktøjsversioner og offline-tests; endnu ikke brugt i et andet repository (MIL-007) ([vejledning til C og C++](QualityChecksCpp.da), [vejledning til C#](QualityChecksCSharp.da)) |
 | Kodemålinger og dækningsbadges | Implementeret og udgivet i 2.1.0 som det genbrugelige workflow `.gitea/workflows/code-metrics.yml` med en tæller, en Cobertura-læser, en SVG-renderer og offline-tests; afprøvet i et kasserepository, endnu ikke brugt i et projektrepository (MIL-010) ([vejledning](CodeMetrics.da)) |
+| Engelske kommentarer | Implementeret som det genbrugelige workflow `.gitea/workflows/english-comments.yml` med en kommentarudtrækker, en sprogdetektor målt på et korpus (ADR-0012), en kommentar på pull requesten og offline-tests; endnu ikke kørt på instansen eller krævet af noget repository (MIL-013) ([vejledning](EnglishComments.da)) |
 | Versioneret udgivelse og publicering | Udgivelsesproces, changelog og opgraderingsvejledning er defineret; udgivelsesworkflowet findes, og `v1.0.0` er udgivet (MIL-004) ([vejledning](Upgrading.da)) |

docs/wiki/Capabilities.md

@@ -17,4 +17,5 @@ Rows that say Implemented or Guides written exist today. The rest is planned and
 | Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adopted in RepoFoundry ([guide](QualityChecksPythonShell)) |
 | Shared quality checks (C and C++, C#) | Implemented as the reusable workflows `.gitea/workflows/quality-checks-cpp.yml` and `.gitea/workflows/quality-checks-csharp.yml` with exact tool versions and offline tests; not yet used in another repository (MIL-007) ([C and C++ guide](QualityChecksCpp), [C# guide](QualityChecksCSharp)) |
 | Code metrics and coverage badges | Implemented and released in 2.1.0 as the reusable workflow `.gitea/workflows/code-metrics.yml` with a counter, a Cobertura reader, an SVG renderer and offline tests; tried in a throwaway repository, not yet used in a project repository (MIL-010) ([guide](CodeMetrics)) |
+| English comments | Implemented as the reusable workflow `.gitea/workflows/english-comments.yml` with a comment extractor, a language detector measured on a corpus (ADR-0012), a pull request comment and offline tests; not yet run on the instance or required by any repository (MIL-013) ([guide](EnglishComments)) |
 | Versioned release and publishing | Release process, changelog and upgrade guide defined; the release workflow exists and `v1.0.0` is released (MIL-004) ([guide](Upgrading)) |

docs/wiki/Capabilities.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Capabilities.md, source sha256 3e3bcd9498f7 -->
+<!-- translation of Capabilities.md, source sha256 a8c14f722a77 -->
 
 > Ini ialah terjemahan [`Capabilities`](Capabilities). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -17,4 +17,5 @@ Baris yang menyatakan Dilaksanakan atau Panduan telah ditulis wujud hari ini. Se
 | Semakan kualiti bersama (Python dan shell) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks.yml`, dengan ujian luar talian dan percubaan dalam organisasi kedua; digunakan dalam RepoFoundry ([panduan](QualityChecksPythonShell.ms)) |
 | Semakan kualiti bersama (C dan C++, C#) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks-cpp.yml` dan `.gitea/workflows/quality-checks-csharp.yml` dengan versi alat yang tepat dan ujian luar talian; belum digunakan dalam repositori lain (MIL-007) ([panduan C dan C++](QualityChecksCpp.ms), [panduan C#](QualityChecksCSharp.ms)) |
 | Metrik kod dan lencana liputan | Dilaksanakan dan diterbitkan dalam 2.1.0 sebagai aliran kerja boleh guna semula `.gitea/workflows/code-metrics.yml` dengan pengira, pembaca Cobertura, pemaparan SVG dan ujian luar talian; dicuba dalam repositori sekali pakai, belum digunakan dalam repositori projek (MIL-010) ([panduan](CodeMetrics.ms)) |
+| Komen dalam bahasa Inggeris | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/english-comments.yml` dengan pengekstrak komen, pengesan bahasa yang diukur pada korpus (ADR-0012), komen pada pull request dan ujian luar talian; belum dijalankan pada instans atau diwajibkan oleh mana-mana repositori (MIL-013) ([panduan](EnglishComments.ms)) |
 | Keluaran berversi dan penerbitan | Proses keluaran, changelog dan panduan naik taraf telah ditakrifkan; aliran kerja keluaran sudah ada dan `v1.0.0` telah dikeluarkan (MIL-004) ([panduan](Upgrading.ms)) |

docs/wiki/EnglishComments.da.md

@@ -0,0 +1,108 @@
+<!-- translation of EnglishComments.md, source sha256 866ce29fd1ea -->
+
+> Dette er en oversættelse af [`EnglishComments`](EnglishComments). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
+
+[English](EnglishComments) | Dansk | [Bahasa Melayu](EnglishComments.ms)
+
+# Kommentarer i kildekoden på engelsk
+
+Sådan kalder en softwareudvikler det fælles workflow, der kontrollerer, at
+kommentarerne og docstrings i en pull request er skrevet på engelsk. Workflowet
+lader kørslen fejle, når én ikke er det, og skriver én kommentar på pull
+requesten, der nævner forfatteren. Det ændrer ingen fil og sender ingen
+kildetekst ud af instansen. Beslutningen bag er ADR-0012 i dette repository.
+
+## Kald af workflowet
+
+```yaml
+name: English comments
+
+on:
+  pull_request:
+
+jobs:
+  english-comments:
+    uses: TirSystem/github-action/.gitea/workflows/english-comments.yml@v2
+    with:
+      exclude: "docs/generated/**"
+      allowed-words-file: .english-comments-allowed-words
+```
+
+Indtil udgivelse 2.3.0 findes workflowet kun på `main`, så kald det med `@main`; `@v2` indeholder det
+endnu ikke.
+
+| Input | Standard | Betydning |
+| --- | --- | --- |
+| `scope` | `changed` | `changed` kontrollerer kommentarerne på de linjer, pull requesten tilføjer; `all` kontrollerer hver sporet fil |
+| `exclude` | | Kommasepareret liste af fil- eller stimønstre, der ikke kontrolleres (`*` og `**` er jokertegn) |
+| `allowed-words-file` | | En fil i repositoryet med ord, der aldrig bedømmes, ét pr. linje; `#` starter en kommentar |
+| `threshold` | `0.6` | Sandsynligheden, over 0 og højst 1, hvorfra en kommentar regnes for ikke at være engelsk |
+| `min-words` | `3` | En kommentar med færre ord bedømmes ikke |
+| `langid-version`, `numpy-version` | `1.1.6`, `2.1.3` | De fastlåste pakker, detektoren bruger |
+| `tools-ref` | den nuværende hovedversion | Det tag i dette repository, hvis scripts køres; fastlås det sammen med workflowet |
+
+Den valgfri secret `REPORT_TOKEN` er et Gitea-token, der må kommentere på pull
+requests. Uden den bruger workflowet kørslens eget token, så kommentaren
+skrives af Actions-botten. En pull request fra en fork har et token med kun
+læseadgang: kontrollen får stadig kørslen til at fejle, men der skrives ingen
+kommentar.
+
+## Hvad der kontrolleres
+
+Kommentarerne og docstrings i filer på de sprog, kodetælleren kender
+([kodemålinger](CodeMetrics)): Python, shell, PowerShell, C, C++, C#, Java,
+JavaScript, TypeScript, Go, Rust og SQL. Strenge og kode læses ikke. Kommentarlinjer
+efter hinanden bedømmes som én blok.
+
+Før en blok bedømmes, fjernes alt, der ikke er et ord: stier, URL'er, tilvalg
+(`--output`), filnavne, identifikatorer (`snake_case`, `camelCase`), tal,
+akronymer og konstanter (`JSON`), en indledende etiket som `Usage:` og ordene
+i filen med tilladte ord. En blok med færre end `min-words` ord tilbage
+bedømmes ikke, så en kort kommentar slipper igennem. Kommentarer, der
+konfigurerer et værktøj (`noqa`, `type:`, `pragma`, `shellcheck`), læses ikke.
+
+## Når kontrollen fejler
+
+Kørslen fejler, hvert fund vises som en annotation (`::error file=...,line=...`)
+og i loggen som `file:line: looks Danish (0.93): "the comment"`, og én kommentar
+på pull requesten opregner dem og nævner forfatteren. En ny kørsel opdaterer den
+kommentar; når pull requesten består, markeres kommentaren som løst og nævner
+ikke længere nogen.
+
+Ret det ved at skrive kommentaren om på engelsk. For et citat eller et navn, der
+ikke er engelsk, kan du enten skrive `english-comments: ignore` i kommentaren
+(det springer hele den kommentarblok over, den står i), eller tilføje ordet til
+filen med tilladte ord.
+
+## Blokering af sammenfletningen
+
+En fejlende kørsel blokerer ikke i sig selv en sammenfletning. Markér kontrollen
+som påkrævet i grenbeskyttelsen af målgrenen: kør workflowet én gang på en pull
+request og vælg dets post på listen over statuskontroller (det præcise navn
+dannes af det kaldende workflow, dets job og hændelsen). At indstille
+grenbeskyttelse er repositoryejerens handling; workflowet ændrer den ikke.
+
+## Hvor præcis den er
+
+Detektoren er `langid`, begrænset til engelsk, dansk, norsk, svensk, tysk,
+fransk, malajisk, indonesisk og hollandsk. På repositoryets korpus markerer den
+ingen af 300 engelske kommentarer, 44 af 45 danske og 41 af 45 malajiske
+kommentarer og alle 48 tyske, svenske, norske og franske (ADR-0012). Dens
+grænser:
+
+- en kommentar på ét eller to ord, eller en der mest består af navne, bedømmes ikke;
+- en kommentar på dårligt engelsk slipper igennem, og en kommentar, der blander
+  engelske fagudtryk med få danske eller malajiske ord, kan slippe igennem;
+- korpussets danske og malajiske kommentarer er skrevet til testen og ikke samlet
+  fra rigtig kode, så rigtig kode vil vise andre fejl. Meld en misset kommentar
+  eller et falsk fund med kommentaren, så kommer den med i korpussen.
+
+## Fejlfinding
+
+| Besked | Årsag |
+| --- | --- |
+| `[configuration] give --base` | Workflowet blev startet af en hændelse, der ikke er en pull request, med `scope: changed`; kald det på `pull_request` eller brug `scope: all` |
+| `[configuration] git diff failed` | Basisgrenen findes ikke i checkout; workflowet henter hele historikken, så tjek at pull requesten har en målgren |
+| `[configuration] langid is not installed` | Installationstrinnet fejlede; tjek de fastlåste versioner |
+| `[permissions] ... may not comment on pull requests` | Tokenet må ikke kommentere; giv `REPORT_TOKEN` skriveadgang til issues og pull requests |
+| Et fund, der ikke er et fund | Tilføj ordene til filen med tilladte ord, eller `english-comments: ignore` til kommentaren |

docs/wiki/EnglishComments.md

@@ -0,0 +1,106 @@
+<!-- Generated from guides/english-comments.md by tools/build_wiki.py. Edit the source, not this page. -->
+
+> This page is generated from [`guides/english-comments.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/english-comments.md). Changes made here are overwritten the next time the wiki is published.
+
+English | [Dansk](EnglishComments.da) | [Bahasa Melayu](EnglishComments.ms)
+
+# Keeping source code comments in English
+
+How a software engineer calls the shared workflow that checks that the comments
+and docstrings of a pull request are written in English. The workflow fails the
+run when one is not, and writes one comment on the pull request that mentions
+the author. It changes no file and sends no source text outside the instance.
+Its decision is ADR-0012 in this repository.
+
+## Calling the workflow
+
+```yaml
+name: English comments
+
+on:
+  pull_request:
+
+jobs:
+  english-comments:
+    uses: TirSystem/github-action/.gitea/workflows/english-comments.yml@v2
+    with:
+      exclude: "docs/generated/**"
+      allowed-words-file: .english-comments-allowed-words
+```
+
+Until release 2.3.0 the workflow exists only on `main`, so call it at `@main`; `@v2` does not
+contain it yet.
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `scope` | `changed` | `changed` checks the comments on the lines the pull request adds; `all` checks every tracked file |
+| `exclude` | | Comma list of file name or path patterns that are not checked (`*` and `**` are wildcards) |
+| `allowed-words-file` | | A file of the repository with words that are never judged, one per line, `#` starts a comment |
+| `threshold` | `0.6` | The probability, above 0 and at most 1, from which a comment counts as not English |
+| `min-words` | `3` | A comment with fewer words is not judged |
+| `langid-version`, `numpy-version` | `1.1.6`, `2.1.3` | The pinned packages the detector needs |
+| `tools-ref` | the current major | The tag of this repository whose scripts are run; pin it together with the workflow |
+
+The optional secret `REPORT_TOKEN` is a Gitea token that may comment on pull
+requests. Without it the workflow uses the token of the run, so the comment is
+written by the Actions bot. A pull request from a fork has a read-only token:
+the check still fails the run, but no comment is written.
+
+## What is checked
+
+The comments and docstrings of the files of the languages in the code counter
+([code metrics](CodeMetrics)): Python, shell, PowerShell, C, C++, C#, Java,
+JavaScript, TypeScript, Go, Rust and SQL. Strings and code are not read.
+Consecutive comment lines are judged as one block.
+
+Before a block is judged, everything that is not a word is removed: paths, URLs,
+options (`--output`), file names, identifiers (`snake_case`, `camelCase`),
+numbers, acronyms and constants (`JSON`), a leading label such as `Usage:`, and
+the words of the allowed-words file. A block with fewer than `min-words` words
+left is not judged, so a short comment passes. Comments that configure a tool
+(`noqa`, `type:`, `pragma`, `shellcheck`) are not read.
+
+## When the check fails
+
+The run fails, each finding is shown as an annotation (`::error file=...,line=...`)
+and in the log as `file:line: looks Danish (0.93): "the comment"`, and one comment
+on the pull request lists them and mentions the author. A new run updates that
+comment; when the pull request passes, the comment is marked resolved and no
+longer mentions anyone.
+
+Fix it by rewriting the comment in English. For a quotation or a name that is
+not English, either put `english-comments: ignore` in the comment (it skips the
+whole comment block it is in), or add the word to the allowed-words file.
+
+## Blocking the merge
+
+A failing run does not block a merge by itself. In the branch protection of the
+target branch, mark the check as required: run the workflow once on a pull
+request and choose its entry in the list of status checks (the exact name is
+made from the calling workflow, its job and the event). Setting branch
+protection is the repository owner's action; the workflow does not change it.
+
+## How accurate it is
+
+The detector is `langid`, limited to English, Danish, Norwegian, Swedish,
+German, French, Malay, Indonesian and Dutch. On the corpus of the repository it
+flags none of 300 English comments, 44 of 45 Danish and 41 of 45 Malay comments
+and all of the 48 German, Swedish, Norwegian and French ones (ADR-0012). Its
+limits:
+
+- a comment of one or two words, or one that is mostly names, is not judged;
+- a comment in poor English passes, and a comment that mixes English technical
+  terms with few Danish or Malay words can pass;
+- the Danish and Malay comments of the corpus were written for the test, not
+  collected from real code, so real code will show other misses. Report a miss
+  or a false positive with the comment, and it joins the corpus.
+
+## Troubleshooting
+
+| Message | Cause |
+| --- | --- |
+| `[configuration] give --base` | The workflow was started by an event that is not a pull request with `scope: changed`; call it on `pull_request` or use `scope: all` |
+| `[configuration] git diff failed` | The base branch is not in the checkout; the workflow fetches the full history, so check that the pull request has a target branch |
+| `[configuration] langid is not installed` | The install step failed; check the pinned versions |
+| `[permissions] ... may not comment on pull requests` | The token cannot comment; give `REPORT_TOKEN` write access to issues and pull requests |
+| A finding that is not a finding | Add the words to the allowed-words file, or `english-comments: ignore` to the comment |

docs/wiki/EnglishComments.ms.md

@@ -0,0 +1,110 @@
+<!-- translation of EnglishComments.md, source sha256 866ce29fd1ea -->
+
+> Ini ialah terjemahan [`EnglishComments`](EnglishComments). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
+
+[English](EnglishComments) | [Dansk](EnglishComments.da) | Bahasa Melayu
+
+# Memastikan komen kod sumber dalam bahasa Inggeris
+
+Cara seorang jurutera perisian memanggil aliran kerja bersama yang menyemak bahawa
+komen dan docstring sesuatu pull request ditulis dalam bahasa Inggeris. Aliran
+kerja menggagalkan larian apabila ada yang bukan bahasa Inggeris, dan menulis satu
+komen pada pull request yang menyebut penulisnya. Ia tidak mengubah sebarang fail
+dan tidak menghantar teks sumber keluar daripada instans. Keputusan di
+belakangnya ialah ADR-0012 dalam repositori ini.
+
+## Memanggil aliran kerja
+
+```yaml
+name: English comments
+
+on:
+  pull_request:
+
+jobs:
+  english-comments:
+    uses: TirSystem/github-action/.gitea/workflows/english-comments.yml@v2
+    with:
+      exclude: "docs/generated/**"
+      allowed-words-file: .english-comments-allowed-words
+```
+
+Sehingga keluaran 2.3.0, aliran kerja hanya wujud pada `main`, jadi panggil dengan `@main`; `@v2` belum
+mengandunginya.
+
+| Input | Lalai | Maksud |
+| --- | --- | --- |
+| `scope` | `changed` | `changed` menyemak komen pada baris yang ditambah oleh pull request; `all` menyemak setiap fail yang dijejaki |
+| `exclude` | | Senarai corak nama fail atau laluan yang dipisahkan koma dan tidak disemak (`*` dan `**` ialah kad liar) |
+| `allowed-words-file` | | Fail dalam repositori dengan perkataan yang tidak pernah dinilai, satu pada setiap baris; `#` memulakan komen |
+| `threshold` | `0.6` | Kebarangkalian, melebihi 0 dan paling banyak 1, yang mulai daripadanya sesuatu komen dianggap bukan bahasa Inggeris |
+| `min-words` | `3` | Komen dengan perkataan yang lebih sedikit tidak dinilai |
+| `langid-version`, `numpy-version` | `1.1.6`, `2.1.3` | Pakej tetap yang diperlukan oleh pengesan |
+| `tools-ref` | major semasa | Tag repositori ini yang skripnya dijalankan; tetapkan bersama aliran kerja |
+
+Secret pilihan `REPORT_TOKEN` ialah token Gitea yang boleh memberi komen pada pull
+request. Tanpanya, aliran kerja menggunakan token larian itu sendiri, jadi komen
+ditulis oleh bot Actions. Pull request daripada fork mempunyai token baca sahaja:
+semakan masih menggagalkan larian, tetapi tiada komen ditulis.
+
+## Apa yang disemak
+
+Komen dan docstring dalam fail bahasa yang dikenali oleh pengira kod
+([metrik kod](CodeMetrics)): Python, shell, PowerShell, C, C++, C#, Java,
+JavaScript, TypeScript, Go, Rust dan SQL. String dan kod tidak dibaca. Baris komen
+yang berturutan dinilai sebagai satu blok.
+
+Sebelum sesuatu blok dinilai, segala yang bukan perkataan dibuang: laluan, URL,
+pilihan (`--output`), nama fail, pengecam (`snake_case`, `camelCase`), nombor,
+akronim dan pemalar (`JSON`), label di permulaan seperti `Usage:`, dan perkataan
+dalam fail perkataan yang dibenarkan. Blok yang tinggal kurang daripada
+`min-words` perkataan tidak dinilai, jadi komen pendek lulus. Komen yang
+mengkonfigurasi alat (`noqa`, `type:`, `pragma`, `shellcheck`) tidak dibaca.
+
+## Apabila semakan gagal
+
+Larian gagal, setiap penemuan dipaparkan sebagai anotasi (`::error file=...,line=...`)
+dan dalam log sebagai `file:line: looks Danish (0.93): "the comment"`, dan satu
+komen pada pull request menyenaraikannya serta menyebut penulisnya. Larian baharu
+mengemas kini komen itu; apabila pull request lulus, komen ditandakan selesai dan
+tidak lagi menyebut sesiapa.
+
+Betulkannya dengan menulis semula komen dalam bahasa Inggeris. Untuk petikan atau
+nama yang bukan bahasa Inggeris, sama ada letakkan `english-comments: ignore`
+dalam komen (ia melangkau seluruh blok komen tempat ia berada), atau tambahkan
+perkataan itu ke dalam fail perkataan yang dibenarkan.
+
+## Menyekat penggabungan
+
+Larian yang gagal tidak menyekat penggabungan dengan sendirinya. Dalam
+perlindungan cabang bagi cabang sasaran, tandakan semakan sebagai wajib: jalankan
+aliran kerja sekali pada sebuah pull request dan pilih entrinya dalam senarai
+semakan status (nama tepatnya dibentuk daripada aliran kerja pemanggil, kerjanya
+dan peristiwa). Menetapkan perlindungan cabang ialah tindakan pemilik repositori;
+aliran kerja tidak mengubahnya.
+
+## Sejauh mana ia tepat
+
+Pengesan ialah `langid`, terhad kepada bahasa Inggeris, Denmark, Norway, Sweden,
+Jerman, Perancis, Melayu, Indonesia dan Belanda. Pada korpus repositori, ia
+menandakan tiada satu pun daripada 300 komen bahasa Inggeris, 44 daripada 45
+komen bahasa Denmark dan 41 daripada 45 komen bahasa Melayu, serta kesemua 48
+komen bahasa Jerman, Sweden, Norway dan Perancis (ADR-0012). Batasannya:
+
+- komen satu atau dua perkataan, atau yang kebanyakannya nama, tidak dinilai;
+- komen dalam bahasa Inggeris yang lemah lulus, dan komen yang mencampurkan istilah
+  teknikal bahasa Inggeris dengan beberapa perkataan Denmark atau Melayu boleh lulus;
+- komen bahasa Denmark dan Melayu dalam korpus ditulis untuk ujian, bukan dikumpulkan
+  daripada kod sebenar, jadi kod sebenar akan menunjukkan kesilapan lain. Laporkan
+  komen yang terlepas atau penemuan palsu bersama komennya, dan ia akan masuk ke
+  dalam korpus.
+
+## Diagnosis
+
+| Mesej | Punca |
+| --- | --- |
+| `[configuration] give --base` | Aliran kerja dimulakan oleh peristiwa yang bukan pull request dengan `scope: changed`; panggil pada `pull_request` atau gunakan `scope: all` |
+| `[configuration] git diff failed` | Cabang asas tiada dalam checkout; aliran kerja mengambil seluruh sejarah, jadi semak bahawa pull request mempunyai cabang sasaran |
+| `[configuration] langid is not installed` | Langkah pemasangan gagal; semak versi yang ditetapkan |
+| `[permissions] ... may not comment on pull requests` | Token tidak boleh memberi komen; berikan `REPORT_TOKEN` akses tulis kepada isu dan pull request |
+| Penemuan yang bukan penemuan | Tambahkan perkataan ke dalam fail perkataan yang dibenarkan, atau `english-comments: ignore` pada komen |

docs/wiki/Home.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Home.md, source sha256 9b967f9e1aff -->
+<!-- translation of Home.md, source sha256 9b84b5cf7534 -->
 
 > Dette er en oversættelse af [`Home`](Home). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -13,12 +13,12 @@ En samling af genbrugelige Gitea Actions-workflows til DevOps-professionelle og
 
 Dette repository er den centrale samling af genbrugelig automatisering til TirSystems repositories. Det primære repository ligger på `git.tirsystem.com` (Gitea) og spejles med push til GitHub.
 
-Det indeholder ti workflows: synkronisering af metadata til GitHub-spejlet, publicering af wiki (kaldt af hvert repository), fælles kvalitetskontrol for Python og shell, for C og C++ og for C#, kodemålinger og dækningsbadges, et udgivelsesworkflow, publicering af accepterede milepæle og repositoryets egen validering. De er listet med formål og diagram under [Workflows](#workflows).
+Det indeholder elleve workflows: synkronisering af metadata til GitHub-spejlet, publicering af wiki (kaldt af hvert repository), fælles kvalitetskontrol for Python og shell, for C og C++ og for C#, kodemålinger og dækningsbadges, en kontrol af, at kommentarer er på engelsk, et udgivelsesworkflow, publicering af accepterede milepæle og repositoryets egen validering. De er listet med formål og diagram under [Workflows](#workflows).
 
 
 ## Workflows
 
-Der er ti workflows i dette repository. Et **scoped** workflow leveres af instansen til alle repositories i TirSystem-organisationerne og kræver intet i repositoryet; et **genbrugeligt** workflow kaldes fra et repository med `uses:`; de øvrige kører kun her. Diagrammerne er PlantUML-kildekode og er på engelsk.
+Der er elleve workflows i dette repository. Et **scoped** workflow leveres af instansen til alle repositories i TirSystem-organisationerne og kræver intet i repositoryet; et **genbrugeligt** workflow kaldes fra et repository med `uses:`; de øvrige kører kun her. Diagrammerne er PlantUML-kildekode og er på engelsk.
 
 | Workflow | Fil | Type | Starter ved | Formål |
 | --- | --- | --- | --- | --- |
@@ -28,6 +28,7 @@ Der er ti workflows i dette repository. Et **scoped** workflow leveres af instan
 | Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører clang-format og clang-tidy i præcise versioner på de sporede C- og C++-filer og ændrer intet |
 | Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører `dotnet format` og `dotnet build` på et præcist .NET SDK 10 eller nyere og ændrer intet |
 | Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/code-metrics.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Tæller kodefilerne og kodelinjerne (uden kommentar- og tomme linjer), læser en Cobertura-dækningsrapport og committer tre SVG-badges til en `badges`-gren |
+| English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/english-comments.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository, på en pull request | Bedømmer sproget i de kommentarer og docstrings, en pull request tilføjer, lader kørslen fejle, når én ikke er engelsk, og skriver én kommentar på pull requesten, der nævner forfatteren |
 | Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | Kun dette repository | push til `main`, der ændrer `docs/wiki/**`, manuelt | Kalder det genbrugelige workflow Publish wiki pages for dette repositorys wiki |
 | Release | [`release.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/release.yml) | Kun dette repository | manuelt | Opretter versionstagget, udgivelsessiden og major-tagget efter kontrollerne |
 | Publicering af accepterede milepæle | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/sync-milestones.yml) | Kun dette repository | push til `main`, der ændrer `docs/milestones/**` eller `docs/sqa/reviews/**`, manuelt (tørkørsel som standard) | Opretter eller opdaterer Gitea-milepælen og issues for hver milepæl, der er Accepted med en Go-gennemgang |
@@ -279,6 +280,46 @@ deactivate Workflow
 @enduml
 ```
 
+### Engelske kommentarer
+
+Et genbrugeligt workflow, der kontrollerer, at de kommentarer og docstrings, en pull request tilføjer, er skrevet på engelsk, lader kørslen fejle, når én ikke er det, og skriver én kommentar på pull requesten, der nævner forfatteren. Det ændrer ingen fil og sender ingen kildetekst ud af instansen; at markere kontrollen som påkrævet i grenbeskyttelsen er det, der blokerer sammenfletningen ([vejledning](EnglishComments.da), ADR-0012).
+
+#### Workflow
+
+```plantuml
+@startuml
+title English comments check (reusable workflow)
+
+autonumber
+
+actor "Pull request
+uses: ...english-comments.yml@v2" as Caller
+participant "Gitea Actions
+english-comments" as Workflow
+participant "Gitea REST API" as Gitea
+
+Caller -> Workflow: workflow_call with scope, exclude,
+allowed-words-file, threshold and min-words
+activate Workflow
+
+Workflow -> Workflow: Check out the full history and the shared scripts
+Workflow -> Workflow: Install the pinned language detector
+Workflow -> Workflow: Read the comments on the added lines
+Workflow -> Workflow: Remove paths, options, identifiers and allowed words
+Workflow -> Workflow: Judge the language of each comment block
+
+alt a block is not English
+  Workflow -> Gitea: Create or update one comment that mentions the author
+  Workflow --> Caller: run failed (the required check blocks the merge)
+else all blocks are English
+  Workflow -> Gitea: Mark an earlier comment resolved
+  Workflow --> Caller: run passed
+end
+
+deactivate Workflow
+@enduml
+```
+
 ### Udgivelse
 
 Startes manuelt af en vedligeholder; med `dry_run` `true` (standard) kontrollerer det kun (se [udgivelsesprocessen](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/release-process.md)).

docs/wiki/Home.md

@@ -13,12 +13,12 @@ A collection of reusable Gitea Actions workflows for DevOps professionals and so
 
 This repository is the central collection of reusable automation for TirSystem repositories. The primary repository lives at `git.tirsystem.com` (Gitea) and is push-mirrored to GitHub.
 
-It contains ten workflows: metadata sync to the GitHub mirror, wiki publishing (called by each repository), shared quality checks for Python and shell, for C and C++ and for C#, code metrics and coverage badges, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#workflows).
+It contains eleven workflows: metadata sync to the GitHub mirror, wiki publishing (called by each repository), shared quality checks for Python and shell, for C and C++ and for C#, code metrics and coverage badges, a check that comments are in English, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#workflows).
 
 
 ## Workflows
 
-Ten workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
+Eleven workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
 
 | Workflow | File | Kind | Starts on | Purpose |
 | --- | --- | --- | --- | --- |
@@ -28,6 +28,7 @@ Ten workflows live in this repository. A **scoped** workflow is delivered by the
 | Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs clang-format and clang-tidy at exact versions on the tracked C and C++ files and changes nothing |
 | Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs `dotnet format` and `dotnet build` on an exact .NET SDK 10 or later and changes nothing |
 | Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/code-metrics.yml) | Reusable (`workflow_call`) | a call from another repository | Counts the code files and the lines of code (without comment and blank lines), reads a Cobertura coverage report and commits three SVG badges to a `badges` branch |
+| English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/english-comments.yml) | Reusable (`workflow_call`) | a call from another repository, on a pull request | Judges the language of the comments and docstrings a pull request adds, fails the run when one is not English and writes one comment on the pull request that mentions the author |
 | Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | This repository only | push to `main` that changes `docs/wiki/**`, manual | Calls the reusable Publish wiki pages workflow for the wiki of this repository |
 | Release | [`release.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/release.yml) | This repository only | manual | Creates the version tag, the release page and the major tag after the checks |
 | Publish accepted milestones | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/sync-milestones.yml) | This repository only | push to `main` that changes `docs/milestones/**` or `docs/sqa/reviews/**`, manual (dry run by default) | Creates or updates the Gitea milestone and issues of every milestone that is Accepted with a Go review |
@@ -279,6 +280,46 @@ deactivate Workflow
 @enduml
 ```
 
+### English comments
+
+A reusable workflow that checks that the comments and docstrings a pull request adds are written in English, fails the run when one is not, and writes one comment on the pull request that mentions the author. It changes no file and sends no source text outside the instance; marking the check as required in the branch protection is what blocks the merge ([guide](EnglishComments), ADR-0012).
+
+#### Workflow
+
+```plantuml
+@startuml
+title English comments check (reusable workflow)
+
+autonumber
+
+actor "Pull request
+uses: ...english-comments.yml@v2" as Caller
+participant "Gitea Actions
+english-comments" as Workflow
+participant "Gitea REST API" as Gitea
+
+Caller -> Workflow: workflow_call with scope, exclude,
+allowed-words-file, threshold and min-words
+activate Workflow
+
+Workflow -> Workflow: Check out the full history and the shared scripts
+Workflow -> Workflow: Install the pinned language detector
+Workflow -> Workflow: Read the comments on the added lines
+Workflow -> Workflow: Remove paths, options, identifiers and allowed words
+Workflow -> Workflow: Judge the language of each comment block
+
+alt a block is not English
+  Workflow -> Gitea: Create or update one comment that mentions the author
+  Workflow --> Caller: run failed (the required check blocks the merge)
+else all blocks are English
+  Workflow -> Gitea: Mark an earlier comment resolved
+  Workflow --> Caller: run passed
+end
+
+deactivate Workflow
+@enduml
+```
+
 ### Release
 
 Started by hand by a maintainer; with `dry_run` `true` (the default) it only checks (see the [release process](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/release-process.md)).

docs/wiki/Home.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Home.md, source sha256 9b967f9e1aff -->
+<!-- translation of Home.md, source sha256 9b84b5cf7534 -->
 
 > Ini ialah terjemahan [`Home`](Home). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -13,12 +13,12 @@ Koleksi aliran kerja (workflow) Gitea Actions yang boleh digunakan semula untuk
 
 Repositori ini ialah koleksi pusat bagi automasi yang boleh digunakan semula untuk repositori TirSystem. Repositori utama berada di `git.tirsystem.com` (Gitea) dan dicerminkan dengan push ke GitHub.
 
-Ia mengandungi sepuluh aliran kerja: penyegerakan metadata ke cermin GitHub, penerbitan wiki (dipanggil oleh setiap repositori), semakan kualiti bersama untuk Python dan shell, untuk C dan C++ serta untuk C#, metrik kod dan lencana liputan, aliran kerja keluaran, penerbitan pencapaian (milestone) yang diterima dan pengesahan repositori sendiri. Ia disenaraikan dengan tujuan dan rajah di bawah [Aliran kerja](#aliran-kerja).
+Ia mengandungi sebelas aliran kerja: penyegerakan metadata ke cermin GitHub, penerbitan wiki (dipanggil oleh setiap repositori), semakan kualiti bersama untuk Python dan shell, untuk C dan C++ serta untuk C#, metrik kod dan lencana liputan, semakan bahawa komen ditulis dalam bahasa Inggeris, aliran kerja keluaran, penerbitan pencapaian (milestone) yang diterima dan pengesahan repositori sendiri. Ia disenaraikan dengan tujuan dan rajah di bawah [Aliran kerja](#aliran-kerja).
 
 
 ## Aliran kerja
 
-Terdapat sepuluh aliran kerja dalam repositori ini. Aliran kerja **scoped** dihantar oleh instans ke setiap repositori organisasi TirSystem dan tidak memerlukan apa-apa dalam repositori; aliran kerja **boleh guna semula** dipanggil oleh sebuah repositori dengan `uses:`; yang lain hanya berjalan di sini. Rajah ialah kod sumber PlantUML dan dalam bahasa Inggeris.
+Terdapat sebelas aliran kerja dalam repositori ini. Aliran kerja **scoped** dihantar oleh instans ke setiap repositori organisasi TirSystem dan tidak memerlukan apa-apa dalam repositori; aliran kerja **boleh guna semula** dipanggil oleh sebuah repositori dengan `uses:`; yang lain hanya berjalan di sini. Rajah ialah kod sumber PlantUML dan dalam bahasa Inggeris.
 
 | Aliran kerja | Fail | Jenis | Bermula apabila | Tujuan |
 | --- | --- | --- | --- | --- |
@@ -28,6 +28,7 @@ Terdapat sepuluh aliran kerja dalam repositori ini. Aliran kerja **scoped** diha
 | Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan clang-format dan clang-tidy pada versi tepat pada fail C dan C++ yang dijejaki dan tidak mengubah apa-apa |
 | Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan `dotnet format` dan `dotnet build` pada .NET SDK 10 atau lebih baharu yang tepat dan tidak mengubah apa-apa |
 | Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/code-metrics.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Mengira fail kod dan baris kod (tanpa baris komen dan baris kosong), membaca laporan liputan Cobertura dan melakukan commit tiga lencana SVG ke cabang `badges` |
+| English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/english-comments.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain, pada pull request | Menilai bahasa komen dan docstring yang ditambah oleh pull request, menggagalkan larian apabila ada yang bukan bahasa Inggeris dan menulis satu komen pada pull request yang menyebut penulisnya |
 | Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | Repositori ini sahaja | push ke `main` yang mengubah `docs/wiki/**`, manual | Memanggil aliran kerja boleh guna semula Publish wiki pages untuk wiki repositori ini |
 | Release | [`release.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/release.yml) | Repositori ini sahaja | manual | Mencipta tag versi, halaman keluaran dan tag major selepas semakan |
 | Menerbitkan milestone yang diterima | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/sync-milestones.yml) | Repositori ini sahaja | push ke `main` yang mengubah `docs/milestones/**` atau `docs/sqa/reviews/**`, manual (larian percubaan secara lalai) | Mencipta atau mengemas kini milestone Gitea dan isu bagi setiap milestone yang Accepted dengan semakan Go |
@@ -279,6 +280,46 @@ deactivate Workflow
 @enduml
 ```
 
+### Komen dalam bahasa Inggeris
+
+Aliran kerja boleh guna semula yang menyemak bahawa komen dan docstring yang ditambah oleh pull request ditulis dalam bahasa Inggeris, menggagalkan larian apabila ada yang tidak, dan menulis satu komen pada pull request yang menyebut penulisnya. Ia tidak mengubah sebarang fail dan tidak menghantar teks sumber keluar daripada instans; menandakan semakan sebagai wajib dalam perlindungan cabang ialah yang menyekat penggabungan ([panduan](EnglishComments.ms), ADR-0012).
+
+#### Aliran kerja
+
+```plantuml
+@startuml
+title English comments check (reusable workflow)
+
+autonumber
+
+actor "Pull request
+uses: ...english-comments.yml@v2" as Caller
+participant "Gitea Actions
+english-comments" as Workflow
+participant "Gitea REST API" as Gitea
+
+Caller -> Workflow: workflow_call with scope, exclude,
+allowed-words-file, threshold and min-words
+activate Workflow
+
+Workflow -> Workflow: Check out the full history and the shared scripts
+Workflow -> Workflow: Install the pinned language detector
+Workflow -> Workflow: Read the comments on the added lines
+Workflow -> Workflow: Remove paths, options, identifiers and allowed words
+Workflow -> Workflow: Judge the language of each comment block
+
+alt a block is not English
+  Workflow -> Gitea: Create or update one comment that mentions the author
+  Workflow --> Caller: run failed (the required check blocks the merge)
+else all blocks are English
+  Workflow -> Gitea: Mark an earlier comment resolved
+  Workflow --> Caller: run passed
+end
+
+deactivate Workflow
+@enduml
+```
+
 ### Keluaran
 
 Dimulakan secara manual oleh penyelenggara; dengan `dry_run` `true` (lalai) ia hanya menyemak (lihat [proses keluaran](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/release-process.md)).

docs/wiki/_Sidebar.md

@@ -12,6 +12,7 @@
 - [Quality checks (C and C++)](QualityChecksCpp)
 - [Quality checks (C#)](QualityChecksCSharp)
 - [Code metrics](CodeMetrics)
+- [English comments](EnglishComments)
 - [Upgrading](Upgrading)
 - [Capabilities](Capabilities)
 
@@ -25,6 +26,7 @@
 - [Kvalitetskontrol (C og C++)](QualityChecksCpp.da)
 - [Kvalitetskontrol (C#)](QualityChecksCSharp.da)
 - [Kodemålinger](CodeMetrics.da)
+- [Engelske kommentarer](EnglishComments.da)
 - [Opgradering](Upgrading.da)
 - [Kapabiliteter](Capabilities.da)
 
@@ -38,5 +40,6 @@
 - [Semakan kualiti (C dan C++)](QualityChecksCpp.ms)
 - [Semakan kualiti (C#)](QualityChecksCSharp.ms)
 - [Metrik kod](CodeMetrics.ms)
+- [Komen dalam bahasa Inggeris](EnglishComments.ms)
 - [Menaik taraf](Upgrading.ms)
 - [Keupayaan](Capabilities.ms)

guides/english-comments.md

@@ -0,0 +1,100 @@
+# Keeping source code comments in English
+
+How a software engineer calls the shared workflow that checks that the comments
+and docstrings of a pull request are written in English. The workflow fails the
+run when one is not, and writes one comment on the pull request that mentions
+the author. It changes no file and sends no source text outside the instance.
+Its decision is ADR-0012 in this repository.
+
+## Calling the workflow
+
+```yaml
+name: English comments
+
+on:
+  pull_request:
+
+jobs:
+  english-comments:
+    uses: TirSystem/github-action/.gitea/workflows/english-comments.yml@v2
+    with:
+      exclude: "docs/generated/**"
+      allowed-words-file: .english-comments-allowed-words
+```
+
+Until release 2.3.0 the workflow exists only on `main`, so call it at `@main`; `@v2` does not
+contain it yet.
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `scope` | `changed` | `changed` checks the comments on the lines the pull request adds; `all` checks every tracked file |
+| `exclude` | | Comma list of file name or path patterns that are not checked (`*` and `**` are wildcards) |
+| `allowed-words-file` | | A file of the repository with words that are never judged, one per line, `#` starts a comment |
+| `threshold` | `0.6` | The probability, above 0 and at most 1, from which a comment counts as not English |
+| `min-words` | `3` | A comment with fewer words is not judged |
+| `langid-version`, `numpy-version` | `1.1.6`, `2.1.3` | The pinned packages the detector needs |
+| `tools-ref` | the current major | The tag of this repository whose scripts are run; pin it together with the workflow |
+
+The optional secret `REPORT_TOKEN` is a Gitea token that may comment on pull
+requests. Without it the workflow uses the token of the run, so the comment is
+written by the Actions bot. A pull request from a fork has a read-only token:
+the check still fails the run, but no comment is written.
+
+## What is checked
+
+The comments and docstrings of the files of the languages in the code counter
+([code metrics](code-metrics.md)): Python, shell, PowerShell, C, C++, C#, Java,
+JavaScript, TypeScript, Go, Rust and SQL. Strings and code are not read.
+Consecutive comment lines are judged as one block.
+
+Before a block is judged, everything that is not a word is removed: paths, URLs,
+options (`--output`), file names, identifiers (`snake_case`, `camelCase`),
+numbers, acronyms and constants (`JSON`), a leading label such as `Usage:`, and
+the words of the allowed-words file. A block with fewer than `min-words` words
+left is not judged, so a short comment passes. Comments that configure a tool
+(`noqa`, `type:`, `pragma`, `shellcheck`) are not read.
+
+## When the check fails
+
+The run fails, each finding is shown as an annotation (`::error file=...,line=...`)
+and in the log as `file:line: looks Danish (0.93): "the comment"`, and one comment
+on the pull request lists them and mentions the author. A new run updates that
+comment; when the pull request passes, the comment is marked resolved and no
+longer mentions anyone.
+
+Fix it by rewriting the comment in English. For a quotation or a name that is
+not English, either put `english-comments: ignore` in the comment (it skips the
+whole comment block it is in), or add the word to the allowed-words file.
+
+## Blocking the merge
+
+A failing run does not block a merge by itself. In the branch protection of the
+target branch, mark the check as required: run the workflow once on a pull
+request and choose its entry in the list of status checks (the exact name is
+made from the calling workflow, its job and the event). Setting branch
+protection is the repository owner's action; the workflow does not change it.
+
+## How accurate it is
+
+The detector is `langid`, limited to English, Danish, Norwegian, Swedish,
+German, French, Malay, Indonesian and Dutch. On the corpus of the repository it
+flags none of 300 English comments, 44 of 45 Danish and 41 of 45 Malay comments
+and all of the 48 German, Swedish, Norwegian and French ones (ADR-0012). Its
+limits:
+
+- a comment of one or two words, or one that is mostly names, is not judged;
+- a comment in poor English passes, and a comment that mixes English technical
+  terms with few Danish or Malay words can pass;
+- the Danish and Malay comments of the corpus were written for the test, not
+  collected from real code, so real code will show other misses. Report a miss
+  or a false positive with the comment, and it joins the corpus.
+
+## Troubleshooting
+
+| Message | Cause |
+| --- | --- |
+| `[configuration] give --base` | The workflow was started by an event that is not a pull request with `scope: changed`; call it on `pull_request` or use `scope: all` |
+| `[configuration] git diff failed` | The base branch is not in the checkout; the workflow fetches the full history, so check that the pull request has a target branch |
+| `[configuration] langid is not installed` | The install step failed; check the pinned versions |
+| `[permissions] ... may not comment on pull requests` | The token cannot comment; give `REPORT_TOKEN` write access to issues and pull requests |
+| A finding that is not a finding | Add the words to the allowed-words file, or `english-comments: ignore` to the comment |

tests/test_build_wiki.py

@@ -106,6 +106,7 @@ def _write_sources(root: Path) -> None:
         "quality-checks-cpp",
         "quality-checks-csharp",
         "code-metrics",
+        "english-comments",
         "upgrading",
     )
     for name in guide_names:

tools/build_wiki.py

@@ -47,6 +47,7 @@ PAGES: tuple[Page, ...] = (
     Page("QualityChecksCpp", "guides/quality-checks-cpp.md"),
     Page("QualityChecksCSharp", "guides/quality-checks-csharp.md"),
     Page("CodeMetrics", "guides/code-metrics.md"),
+    Page("EnglishComments", "guides/english-comments.md"),
     Page("Upgrading", "guides/upgrading.md"),
     Page("Capabilities", "README.md", ("Capabilities",)),
 )
@@ -68,6 +69,7 @@ _PAGE_FOR_SOURCE = {
     "guides/quality-checks-cpp.md": "QualityChecksCpp",
     "guides/quality-checks-csharp.md": "QualityChecksCSharp",
     "guides/code-metrics.md": "CodeMetrics",
+    "guides/english-comments.md": "EnglishComments",
     "guides/upgrading.md": "Upgrading",
 }
 
@@ -193,9 +195,9 @@ def render_page(page: Page, repo_root: Path = REPO_ROOT) -> str:
 # Link text of the sidebar: English, then one list per translation code.
 SIDEBAR_TITLE = "TirSystem GitHub Actions"
 SIDEBAR_LABELS: dict[str, tuple[str, ...]] = {
-    "en": ("Home", "Onboarding", "Credentials", "Troubleshooting", "Quality checks (Python, shell)", "Quality checks (C and C++)", "Quality checks (C#)", "Code metrics", "Upgrading", "Capabilities"),
-    "da": ("Hjem", "Tilslutning", "Credentials", "Fejlfinding", "Kvalitetskontrol (Python, shell)", "Kvalitetskontrol (C og C++)", "Kvalitetskontrol (C#)", "Kodemålinger", "Opgradering", "Kapabiliteter"),
-    "ms": ("Utama", "Menyertakan", "Kelayakan", "Diagnosis", "Semakan kualiti (Python, shell)", "Semakan kualiti (C dan C++)", "Semakan kualiti (C#)", "Metrik kod", "Menaik taraf", "Keupayaan"),
+    "en": ("Home", "Onboarding", "Credentials", "Troubleshooting", "Quality checks (Python, shell)", "Quality checks (C and C++)", "Quality checks (C#)", "Code metrics", "English comments", "Upgrading", "Capabilities"),
+    "da": ("Hjem", "Tilslutning", "Credentials", "Fejlfinding", "Kvalitetskontrol (Python, shell)", "Kvalitetskontrol (C og C++)", "Kvalitetskontrol (C#)", "Kodemålinger", "Engelske kommentarer", "Opgradering", "Kapabiliteter"),
+    "ms": ("Utama", "Menyertakan", "Kelayakan", "Diagnosis", "Semakan kualiti (Python, shell)", "Semakan kualiti (C dan C++)", "Semakan kualiti (C#)", "Metrik kod", "Komen dalam bahasa Inggeris", "Menaik taraf", "Keupayaan"),
 }
 SIDEBAR_NAME = "_Sidebar.md"