# 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:

    @Test
    public void test_matchLocale() {
        assertFalse(labelTypeHelper.matchLocale(Locale.ENGLISH, Locale.JAPANESE));
        assertFalse(labelTypeHelper.matchLocale(Locale.SIMPLIFIED_CHINESE, Locale.TRADITIONAL_CHINESE));

        assertTrue(labelTypeHelper.matchLocale(null, Locale.ROOT));
        assertTrue(labelTypeHelper.matchLocale(Locale.ENGLISH, Locale.ROOT));
        assertTrue(labelTypeHelper.matchLocale(Locale.ROOT, Locale.ROOT));

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.

- Translate headings using the infinite form.

Examples:

Source (English):

```
## Create a Project { #create-a-project }
```

Result (German):

```
## Ein Projekt erstellen { #create-a-project }
```

Do NOT translate with (German):

```
## Erstellen Sie ein Projekt { #create-a-project }
```

Source (English):

```
# Install Packages { #install-packages }
```

Keep class names, function names, modules, file names, and CLI commands unchanged.

### List of English terms and their preferred French translations

Below is a list of English terms and their preferred French translations, separated by a colon (:). Use these translations, do not use your own. If an existing translation does not use these terms, update it to use them.

                .toLowerCase(Locale.ENGLISH);
        String actualOsArch = context.getSystemProperties()
                .getOrDefault("os.arch", Os.OS_ARCH)
                .toLowerCase(Locale.ENGLISH);
        String actualOsVersion = context.getSystemProperties()
                .getOrDefault("os.version", Os.OS_VERSION)
                .toLowerCase(Locale.ENGLISH);

        if (active && os.getFamily() != null) {

            [
                "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.",

### `///` admonitions

- Keep the admonition keyword in English (do not translate `note`, `tip`, etc.).
- If a title is present, prefer these canonical titles:

- `/// note | Not`
- `/// note | Teknik Detaylar`
- `/// tip | İpucu`

        return super.godHandPrologue(runtime);
    }

    /**
     * Converts validation messages to a localized string representation for API responses.
     * Uses the request locale if available, otherwise defaults to English.
     *
     * @param validationMessagesLambda lambda function that adds validation messages
     * @return concatenated string of localized validation messages separated by spaces
     */

- If a heading contains only the name of a FastAPI feature, do not translate it.

### Quotes and punctuation

- Keep punctuation style consistent with existing Simplified Chinese docs (they often mix English terms like “FastAPI” with Chinese text).
- Never change punctuation inside inline code, code blocks, URLs, or file paths.

### Ellipsis

- Keep ellipsis style consistent within each document, prefer `...` over  `……`.