# ADR-0009 - Use American English

## Date

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:

### Quotes

1) Convert neutral double quotes («"») and English double typographic quotes («“» and «”») to French guillemets (««» and «»»).

2) In the French docs, guillemets are written without extra spaces: use «texte», not « texte ».

3) Do not convert quotes inside code blocks, inline code, paths, URLs, or anything wrapped in backticks.

Examples:

    Source (English):

        «««
        "Hello world"

                .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) {

- path operation: 路徑操作
- path operation function: 路徑操作函式

The translation can optionally include the original English text only in the first occurrence of each page (e.g. "路徑操作 (path operation)") if the translation is hard to be comprehended by most of the Chinese readers.

### `///` admonitions

1) Keep the admonition keyword in English (do not translate `note`, `tip`, etc.).

        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
     */

		}
	}
}

func TestParseTagSettingWithDoubleQuoteEscape(t *testing.T) {
	tag := `gorm:"expression:to_tsvector('english', \"Name\")"`
	settings := ParseTagSetting(reflect.StructTag(tag).Get("gorm"), ";")
	if v, ok := settings["EXPRESSION"]; !ok || v != `to_tsvector('english', "Name")` {
		t.Errorf("ParseTagSetting did not handle escaped double quotes correctly: got %#v", v)
	}

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

### Quotes and punctuation

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

### Ellipsis

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

    /**
     * The OA architecture.
     */
    public static final String OS_ARCH = System.getProperty("os.arch").toLowerCase(Locale.ENGLISH);

    /**
     * The OS version.
     */
    public static final String OS_VERSION = System.getProperty("os.version").toLowerCase(Locale.ENGLISH);

    /**
     * OS Family
     */

+
/
\
《
》
—
－
，
。
、
：
；
！
·
？
“
”
）
（
【
】
［
］
●
# the line below contains an IDEOGRAPHIC SPACE character (Used as a space in Chinese)
　

# English Stop Words

    }

    /**
     * @throws Exception
     */
    @Test
    public void testErrorMessage_en() throws Exception {
        // ## Arrange ##
        Locale.setDefault(Locale.ENGLISH);
        final NullArgumentException nullArgumentException = new NullArgumentException("hoge");
        assertThat(nullArgumentException.getArgName(), is("hoge"));