Jun 12, 2025 · Jun 17, 2025 · Jun 17, 2025 · Jun 17, 2025 · Jun 17, 2025 · Jun 21, 2025
diff --git a/docs/guide.md b/docs/guide.md
  - [Proxying to a Svelte app](#proxying-to-a-svelte-app)
  - [Prefixing `/absproxy/<port>` with a path](#prefixing-absproxyport-with-a-path)
  - [Preflight requests](#preflight-requests)
 - [Internationalization and customization](#internationalization-and-customization)
  - [Available keys and placeholders](#available-keys-and-placeholders)
  - [Legacy flag](#legacy-flag)

 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- prettier-ignore-end -->
 requests including preflight requests. This can cause issues because preflight
 requests do not typically include credentials. To allow all preflight requests
 through the proxy without authentication, use `--skip-auth-preflight`.

 ## Internationalization and customization

 code-server allows you to provide a JSON file to configure certain strings. This can be used for both internationalization and customization.

 Create a JSON file with your custom strings:

 ```json
 {
  "WELCOME": "Welcome to {{app}}",
  "LOGIN_TITLE": "{{app}} Access Portal",
  "LOGIN_BELOW": "Please log in to continue",
  "PASSWORD_PLACEHOLDER": "Enter Password"
 }
 ```

 Then reference the file:

 ```shell
 code-server --i18n /path/to/custom-strings.json
 ```

 Or this can be done in the config file:

 ```yaml
 i18n: /path/to/custom-strings.json
 ```

 You can combine this with the `--locale` flag to configure language support for both code-server and VS Code in cases where code-server has no support but VS Code does. If you are using this for internationalization, please consider sending us a pull request to contribute it to `src/node/i18n/locales`.

 ### Available keys and placeholders

 Refer to [../src/node/i18n/locales/en.json](../src/node/i18n/locales/en.json) for a full list of the available keys for translations. Note that the only placeholders supported for each key are the ones used in the default string.

 The `--app-name` flag controls the `{{app}}` placeholder in templates. If you want to change the name, you can either:

 1. Set `--app-name` (potentially alongside `--i18n`)
 2. Use `--i18n` and hardcode the name in your strings

 ### Legacy flag

 The `--welcome-text` flag is now deprecated. Use the `WELCOME` key instead.
diff --git a/src/node/cli.ts b/src/node/cli.ts
  "app-name"?: string
  "welcome-text"?: string
  "abs-proxy-base-path"?: string
  i18n?: string
  /* Positional arguments. */
  _?: string[]
 }
  "app-name": {
    type: "string",
    short: "an",
    description: "The name to use in branding. Will be shown in titlebar and welcome message",
    description:
      "Will replace the {{app}} placeholder in any strings, which by default includes the title bar and welcome message",
  },
  "welcome-text": {
    type: "string",
    short: "w",
    description: "Text to show on login page",
    deprecated: true,
  },
  "abs-proxy-base-path": {
    type: "string",
    description: "The base path to prefix to all absproxy requests",
  },
  i18n: {
    type: "string",
    path: true,
    description: "Path to JSON file with custom translations. Merges with default strings and supports all i18n keys.",
  },
 }

 export const optionDescriptions = (opts: Partial<Options<Required<UserProvidedArgs>>> = options): string[] => {
diff --git a/src/node/i18n/index.ts b/src/node/i18n/index.ts
 import { promises as fs } from "fs"
 import i18next, { init } from "i18next"
 import * as en from "./locales/en.json"
 import * as ja from "./locales/ja.json"
 import * as th from "./locales/th.json"
 import * as ur from "./locales/ur.json"
 import * as zhCn from "./locales/zh-cn.json"

 const defaultResources = {
  en: {
    translation: en,
  },
  "zh-cn": {
    translation: zhCn,
  },
  th: {
    translation: th,
  },
  ja: {
    translation: ja,
  },
  ur: {
    translation: ur,
  },
 }

 export async function loadCustomStrings(filePath: string): Promise<void> {
  try {
    // Read custom strings from file path only
    const fileContent = await fs.readFile(filePath, "utf8")
    const customStringsData = JSON.parse(fileContent)

    // User-provided strings override all languages.
    Object.keys(defaultResources).forEach((locale) => {
      i18next.addResourceBundle(locale, "translation", customStringsData)
    })
  } catch (error) {
    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
      throw new Error(`Custom strings file not found: ${filePath}\nPlease ensure the file exists and is readable.`)
    } else if (error instanceof SyntaxError) {
      throw new Error(`Invalid JSON in custom strings file: ${filePath}\n${error.message}`)
    } else {
      throw new Error(
        `Failed to load custom strings from ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
      )
    }
  }
 }

 init({
  lng: "en",
  fallbackLng: "en", // language to use if translations in user language are not available.
  returnNull: false,
  lowerCaseLng: true,
  debug: process.env.NODE_ENV === "development",
  resources: {
    en: {
      translation: en,
    },
    "zh-cn": {
      translation: zhCn,
    },
    th: {
      translation: th,
    },
    ja: {
      translation: ja,
    },
    ur: {
      translation: ur,
    },
  },
  resources: defaultResources,
 })

 export default i18next
diff --git a/src/node/main.ts b/src/node/main.ts
 import { createApp, ensureAddress } from "./app"
 import { AuthType, DefaultedArgs, Feature, toCodeArgs, UserProvidedArgs } from "./cli"
 import { commit, version, vsRootPath } from "./constants"
 import { loadCustomStrings } from "./i18n"
 import { register } from "./routes"
 import { VSCodeModule } from "./routes/vscode"
 import { isDirectory, open } from "./util"
 ): Promise<{ dispose: Disposable["dispose"]; server: http.Server }> => {
  logger.info(`code-server ${version} ${commit}`)

  // Load custom strings if provided
  if (args.i18n) {
    await loadCustomStrings(args.i18n)
    logger.info("Loaded custom strings")
  }

  logger.info(`Using user-data-dir ${args["user-data-dir"]}`)
  logger.debug(`Using extensions-dir ${args["extensions-dir"]}`)

diff --git a/src/node/routes/login.ts b/src/node/routes/login.ts
  const locale = req.args["locale"] || "en"
  i18n.changeLanguage(locale)
  const appName = req.args["app-name"] || "code-server"
  const welcomeText = req.args["welcome-text"] || (i18n.t("WELCOME", { app: appName }) as string)
  const welcomeText = escapeHtml(req.args["welcome-text"] || (i18n.t("WELCOME", { app: appName }) as string))

  // Determine password message using i18n
  let passwordMsg = i18n.t("LOGIN_PASSWORD", { configFile: req.args.config })
  if (req.args.usingEnvPassword) {
    passwordMsg = i18n.t("LOGIN_USING_ENV_PASSWORD")
  } else if (req.args.usingEnvHashedPassword) {
    passwordMsg = i18n.t("LOGIN_USING_HASHED_PASSWORD")
  }
  passwordMsg = escapeHtml(passwordMsg)

  // Get messages from i18n (with HTML escaping for security)
  const loginTitle = escapeHtml(i18n.t("LOGIN_TITLE", { app: appName }))
  const loginBelow = escapeHtml(i18n.t("LOGIN_BELOW"))
  const passwordPlaceholder = escapeHtml(i18n.t("PASSWORD_PLACEHOLDER"))
  const submitText = escapeHtml(i18n.t("SUBMIT"))

  return replaceTemplates(
    req,
    content
      .replace(/{{I18N_LOGIN_TITLE}}/g,i18n.t("LOGIN_TITLE", { app: appName }))
      .replace(/{{I18N_LOGIN_TITLE}}/g,loginTitle)
      .replace(/{{WELCOME_TEXT}}/g, welcomeText)
      .replace(/{{PASSWORD_MSG}}/g, passwordMsg)
      .replace(/{{I18N_LOGIN_BELOW}}/g,i18n.t("LOGIN_BELOW"))
      .replace(/{{I18N_PASSWORD_PLACEHOLDER}}/g,i18n.t("PASSWORD_PLACEHOLDER"))
      .replace(/{{I18N_SUBMIT}}/g,i18n.t("SUBMIT"))
      .replace(/{{I18N_LOGIN_BELOW}}/g,loginBelow)
      .replace(/{{I18N_PASSWORD_PLACEHOLDER}}/g,passwordPlaceholder)
      .replace(/{{I18N_SUBMIT}}/g,submitText)
      .replace(/{{ERROR}}/, error ? `<div class="error">${escapeHtml(error.message)}</div>` : ""),
  )
 }
diff --git a/test/unit/node/cli.test.ts b/test/unit/node/cli.test.ts
          "--verbose",
          ["--app-name", "custom instance name"],
          ["--welcome-text", "welcome to code"],
          ["--i18n", "path/to/custom-strings.json"],
          "2",

          ["--locale", "ja"],
      verbose: true,
      "app-name": "custom instance name",
      "welcome-text": "welcome to code",
      i18n: path.resolve("path/to/custom-strings.json"),
      version: true,
      "bind-addr": "192.169.0.1:8080",
      "session-socket": "/tmp/override-code-server-ipc-socket",
    })
  })

  it("should parse i18n flag with file path", async () => {
    // Test with file path (no validation at CLI parsing level)
    const args = parse(["--i18n", "/path/to/custom-strings.json"])
    expect(args).toEqual({
      i18n: "/path/to/custom-strings.json",
    })
  })

  it("should parse i18n flag with relative file path", async () => {
    // Test with relative file path
    expect(() => parse(["--i18n", "./custom-strings.json"])).not.toThrow()
    expect(() => parse(["--i18n", "strings.json"])).not.toThrow()
  })

  it("should support app-name and deprecated welcome-text flags", async () => {
    const args = parse(["--app-name", "My App", "--welcome-text", "Welcome!"])
    expect(args).toEqual({
      "app-name": "My App",
      "welcome-text": "Welcome!",
    })
  })

  it("should use env var github token", async () => {
    process.env.GITHUB_TOKEN = "ga-foo"
    const args = parse([])
Original file line number	Diff line number	Diff line change
Expand Up		@@ -22,6 +22,9 @@
		- [Proxying to a Svelte app](#proxying-to-a-svelte-app)
		- [Prefixing `/absproxy/<port>` with a path](#prefixing-absproxyport-with-a-path)
		- [Preflight requests](#preflight-requests)
		- [Internationalization and customization](#internationalization-and-customization)
		- [Available keys and placeholders](#available-keys-and-placeholders)
		- [Legacy flag](#legacy-flag)

		<!-- END doctoc generated TOC please keep comment here to allow auto update -->
		<!-- prettier-ignore-end -->
Expand DownExpand Up		@@ -458,3 +461,45 @@ By default, if you have auth enabled, code-server will authenticate all proxied
		requests including preflight requests. This can cause issues because preflight
		requests do not typically include credentials. To allow all preflight requests
		through the proxy without authentication, use `--skip-auth-preflight`.

		## Internationalization and customization

		code-server allows you to provide a JSON file to configure certain strings. This can be used for both internationalization and customization.

		Create a JSON file with your custom strings:

		```json
		{
		"WELCOME": "Welcome to {{app}}",
		"LOGIN_TITLE": "{{app}} Access Portal",
		"LOGIN_BELOW": "Please log in to continue",
		"PASSWORD_PLACEHOLDER": "Enter Password"
		}
		```

		Then reference the file:

		```shell
		code-server --i18n /path/to/custom-strings.json
		```

		Or this can be done in the config file:

		```yaml
		i18n: /path/to/custom-strings.json
		```

		You can combine this with the `--locale` flag to configure language support for both code-server and VS Code in cases where code-server has no support but VS Code does. If you are using this for internationalization, please consider sending us a pull request to contribute it to `src/node/i18n/locales`.

		### Available keys and placeholders

		Refer to [../src/node/i18n/locales/en.json](../src/node/i18n/locales/en.json) for a full list of the available keys for translations. Note that the only placeholders supported for each key are the ones used in the default string.

		The `--app-name` flag controls the `{{app}}` placeholder in templates. If you want to change the name, you can either:

		1. Set `--app-name` (potentially alongside `--i18n`)
		2. Use `--i18n` and hardcode the name in your strings

		### Legacy flag

		The `--welcome-text` flag is now deprecated. Use the `WELCOME` key instead.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -93,6 +93,7 @@ export interface UserProvidedArgs extends UserProvidedCodeArgs {
		"app-name"?: string
		"welcome-text"?: string
		"abs-proxy-base-path"?: string
		i18n?: string
		/* Positional arguments. */
		_?: string[]
		}
Expand DownExpand Up		@@ -284,17 +285,24 @@ export const options: Options<Required<UserProvidedArgs>> = {
		"app-name": {
		type: "string",
		short: "an",
		description: "The name to use in branding. Will be shown in titlebar and welcome message",
		description:
		"Will replace the {{app}} placeholder in any strings, which by default includes the title bar and welcome message",
		},
		"welcome-text": {
		type: "string",
		short: "w",
		description: "Text to show on login page",
		deprecated: true,
		},
		"abs-proxy-base-path": {
		type: "string",
		description: "The base path to prefix to all absproxy requests",
		},
		i18n: {
		type: "string",
		path: true,
		description: "Path to JSON file with custom translations. Merges with default strings and supports all i18n keys.",
		},
		}

		export const optionDescriptions = (opts: Partial<Options<Required<UserProvidedArgs>>> = options): string[] => {
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,33 +1,59 @@
		import { promises as fs } from "fs"
		import i18next, { init } from "i18next"
		import * as en from "./locales/en.json"
		import * as ja from "./locales/ja.json"
		import * as th from "./locales/th.json"
		import * as ur from "./locales/ur.json"
		import * as zhCn from "./locales/zh-cn.json"

		const defaultResources = {
		en: {
		translation: en,
		},
		"zh-cn": {
		translation: zhCn,
		},
		th: {
		translation: th,
		},
		ja: {
		translation: ja,
		},
		ur: {
		translation: ur,
		},
		}

		export async function loadCustomStrings(filePath: string): Promise<void> {
		try {
		// Read custom strings from file path only
		const fileContent = await fs.readFile(filePath, "utf8")
		const customStringsData = JSON.parse(fileContent)

		// User-provided strings override all languages.
		Object.keys(defaultResources).forEach((locale) => {
		i18next.addResourceBundle(locale, "translation", customStringsData)
		})
		} catch (error) {
		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
		throw new Error(`Custom strings file not found: ${filePath}\nPlease ensure the file exists and is readable.`)
		} else if (error instanceof SyntaxError) {
		throw new Error(`Invalid JSON in custom strings file: ${filePath}\n${error.message}`)
		} else {
		throw new Error(
		`Failed to load custom strings from ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
		)
		}
		}
		}

		init({
		lng: "en",
		fallbackLng: "en", // language to use if translations in user language are not available.
		returnNull: false,
		lowerCaseLng: true,
		debug: process.env.NODE_ENV === "development",
		resources: {
		en: {
		translation: en,
		},
		"zh-cn": {
		translation: zhCn,
		},
		th: {
		translation: th,
		},
		ja: {
		translation: ja,
		},
		ur: {
		translation: ur,
		},
		},
		resources: defaultResources,
		})

		export default i18next
Original file line number	Diff line number	Diff line change
Expand Up		@@ -7,6 +7,7 @@ import { plural } from "../common/util"
		import { createApp, ensureAddress } from "./app"
		import { AuthType, DefaultedArgs, Feature, toCodeArgs, UserProvidedArgs } from "./cli"
		import { commit, version, vsRootPath } from "./constants"
		import { loadCustomStrings } from "./i18n"
		import { register } from "./routes"
		import { VSCodeModule } from "./routes/vscode"
		import { isDirectory, open } from "./util"
Expand DownExpand Up		@@ -122,6 +123,12 @@ export const runCodeServer = async (
		): Promise<{ dispose: Disposable["dispose"]; server: http.Server }> => {
		logger.info(`code-server ${version} ${commit}`)

		// Load custom strings if provided
		if (args.i18n) {
		await loadCustomStrings(args.i18n)
		logger.info("Loaded custom strings")
		}

		logger.info(`Using user-data-dir ${args["user-data-dir"]}`)
		logger.debug(`Using extensions-dir ${args["extensions-dir"]}`)

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -31,23 +31,32 @@ const getRoot = async (req: Request, error?: Error): Promise<string> => {
		const locale = req.args["locale"] \|\| "en"
		i18n.changeLanguage(locale)
		const appName = req.args["app-name"] \|\| "code-server"
		const welcomeText = req.args["welcome-text"] \|\| (i18n.t("WELCOME", { app: appName }) as string)
		const welcomeText = escapeHtml(req.args["welcome-text"] \|\| (i18n.t("WELCOME", { app: appName }) as string))

		// Determine password message using i18n
		let passwordMsg = i18n.t("LOGIN_PASSWORD", { configFile: req.args.config })
		if (req.args.usingEnvPassword) {
		passwordMsg = i18n.t("LOGIN_USING_ENV_PASSWORD")
		} else if (req.args.usingEnvHashedPassword) {
		passwordMsg = i18n.t("LOGIN_USING_HASHED_PASSWORD")
		}
		passwordMsg = escapeHtml(passwordMsg)

		// Get messages from i18n (with HTML escaping for security)
		const loginTitle = escapeHtml(i18n.t("LOGIN_TITLE", { app: appName }))
		const loginBelow = escapeHtml(i18n.t("LOGIN_BELOW"))
		const passwordPlaceholder = escapeHtml(i18n.t("PASSWORD_PLACEHOLDER"))
		const submitText = escapeHtml(i18n.t("SUBMIT"))

		return replaceTemplates(
		req,
		content
		.replace(/{{I18N_LOGIN_TITLE}}/g,i18n.t("LOGIN_TITLE", { app: appName }))
		.replace(/{{I18N_LOGIN_TITLE}}/g,loginTitle)
		.replace(/{{WELCOME_TEXT}}/g, welcomeText)
		.replace(/{{PASSWORD_MSG}}/g, passwordMsg)
		.replace(/{{I18N_LOGIN_BELOW}}/g,i18n.t("LOGIN_BELOW"))
		.replace(/{{I18N_PASSWORD_PLACEHOLDER}}/g,i18n.t("PASSWORD_PLACEHOLDER"))
		.replace(/{{I18N_SUBMIT}}/g,i18n.t("SUBMIT"))
		.replace(/{{I18N_LOGIN_BELOW}}/g,loginBelow)
		.replace(/{{I18N_PASSWORD_PLACEHOLDER}}/g,passwordPlaceholder)
		.replace(/{{I18N_SUBMIT}}/g,submitText)
		.replace(/{{ERROR}}/, error ? `<div class="error">${escapeHtml(error.message)}</div>` : ""),
		)
		}
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -75,6 +75,7 @@ describe("parser", () => {
		"--verbose",
		["--app-name", "custom instance name"],
		["--welcome-text", "welcome to code"],
		["--i18n", "path/to/custom-strings.json"],
		"2",

		["--locale", "ja"],
Expand DownExpand Up		@@ -145,6 +146,7 @@ describe("parser", () => {
		verbose: true,
		"app-name": "custom instance name",
		"welcome-text": "welcome to code",
		i18n: path.resolve("path/to/custom-strings.json"),
		version: true,
		"bind-addr": "192.169.0.1:8080",
		"session-socket": "/tmp/override-code-server-ipc-socket",
Expand DownExpand Up		@@ -347,6 +349,28 @@ describe("parser", () => {
		})
		})

		it("should parse i18n flag with file path", async () => {
		// Test with file path (no validation at CLI parsing level)
		const args = parse(["--i18n", "/path/to/custom-strings.json"])
		expect(args).toEqual({
		i18n: "/path/to/custom-strings.json",
		})
		})

		it("should parse i18n flag with relative file path", async () => {
		// Test with relative file path
		expect(() => parse(["--i18n", "./custom-strings.json"])).not.toThrow()
		expect(() => parse(["--i18n", "strings.json"])).not.toThrow()
		})

		it("should support app-name and deprecated welcome-text flags", async () => {
		const args = parse(["--app-name", "My App", "--welcome-text", "Welcome!"])
		expect(args).toEqual({
		"app-name": "My App",
		"welcome-text": "Welcome!",
		})
		})

		it("should use env var github token", async () => {
		process.env.GITHUB_TOKEN = "ga-foo"
		const args = parse([])
Expand Down