# ADR-0009 - Use American English

## Status

- ACCEPTED on 2025-11-24

## Context

Gradle is an international open-source project with contributors from around the world. English is the primary language for code, comments, documentation, and communication, but there are variations in English spelling and terminology, specifically American English vs. British English.

Inconsistency in spelling conventions can lead to several issues:

Translate an English original content to a target language.

The original content is written in Markdown, write the translation in Markdown as well.

The original content will be surrounded by triple percentage signs (%%%). Do not include the triple percentage signs in the translation.

### Technical terms in English

For technical terms in English that don't have a common translation term, use the original term in English.

            [
                "There is an existing previous translation for the original English content, that may be outdated.",
                "Update the translation only where necessary:",
                "- If the original English content has added parts, also add these parts to the translation.",

      language:
        description: Language to translate to as a letter code (e.g. "es" for Spanish)
        type: string
        required: false
        default: ""
      en_path:
        description: File path in English to translate (e.g. docs/en/docs/index.md)
        type: string
        required: false
        default: ""
      commit_in_place:
        description: Commit changes directly instead of making a PR
        type: boolean

* Check if things are okay in the translation.
* If necessary, improve your language specific prompt, the general prompt, or the English document.
* Then manually fix the remaining issues in the translation, so that it is a good translation.

`secrets.compare_digest()` needs to take `bytes` or a `str` that only contains ASCII characters (the ones in English), this means it wouldn't work with characters like `á`, as in `Sebastián`.

To handle that, we first convert the `username` and `password` to `bytes` encoding them with UTF-8.

    }

    @Test
    public void test_detectLanguage_withoutDetector() {
        // Without a real detector, this would cause NullPointerException
        try {
            languageHelper.detectLanguage("This is English text");
            fail("Should throw NullPointerException without detector");
        } catch (NullPointerException e) {
            // Expected
        }
    }

    @Test

  - icon: fontawesome/brands/linkedin
    link: https://www.linkedin.com/company/fastapi
  - icon: fontawesome/solid/globe
    link: https://tiangolo.com
  alternate:
  - link: /
    name: en - English
  - link: /de/
    name: de - Deutsch
  - link: /es/
    name: es - español
  - link: /fr/
    name: fr - français
  - link: /ja/
    name: ja - 日本語
  - link: /ko/
    name: ko - 한국어

That way, you can edit the documentation/source files and see the changes live.

/// tip

Alternatively, you can perform the same steps that scripts does manually.

Go into the language directory, for the main docs in English it's at `docs/en/`:

```console
$ cd docs/en/
```

Then run `mkdocs` in that directory:

```console
$ mkdocs serve --dev-addr 127.0.0.1:8008
```

///

#### Typer CLI (optional)

    * You can normally quickly detect it by going to the "Files changed" tab in the PR and checking if the updated file(s) starts with `docs/en/docs`. The original version of the docs is always in English, so in `docs/en/docs`.
* `lang-all`: Translations