refactor: simplify --i18n flag to file-only approach

Replace dual JSON/file path functionality with file-only approach for cleaner,
more predictable behavior. Since this is a new feature that hasn't been
released yet, this change eliminates potential user confusion without
breaking existing workflows.

Changes:
- Modify loadCustomStrings() to only accept file paths
- Enhanced error handling with specific messages for file vs JSON errors
- Remove inline JSON parsing from CLI argument handling
- Update flag description to reflect file-only approach
- Add comprehensive test suite covering all error scenarios
- Update documentation to show only file-based examples

Benefits:
- Eliminates semantic ambiguity about argument format
- Clearer error messages (file not found vs invalid JSON)
- Follows Unix conventions for configuration files
- Simpler implementation with better TypeScript typing
- Can enhance with inline JSON later if demand exists

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: strickvl

docs/guide.md

@@ -461,22 +461,29 @@ through the proxy without authentication, use `--skip-auth-preflight`.
 
 ## Internationalization and customization
 
-code-server allows you to provide a language file or JSON to configure certain strings. This can be used for both 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.
 
-For example:
+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 /custom-strings.json
-code-server --i18n '{"WELCOME": "{{app}} ログイン"}'
+code-server --i18n /path/to/custom-strings.json
 ```
 
 Or this can be done in the config file:
 
 ```yaml
-i18n: |
-  {
-    "WELCOME": "Welcome to the {{app}} Development Portal"
-  }
+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`.

src/node/cli.ts

@@ -299,7 +299,7 @@ export const options: Options<Required<UserProvidedArgs>> = {
   },
   i18n: {
     type: "string",
-    description: "Path to JSON file or raw JSON string with custom translations. Merges with default strings and supports all i18n keys.",
+    description: "Path to JSON file with custom translations. Merges with default strings and supports all i18n keys.",
   },
 }
 

src/node/i18n/index.ts

@@ -25,26 +25,24 @@ const defaultResources = {
 }
 
 
-export async function loadCustomStrings(customStringsArg: string): Promise<void> {
-
+export async function loadCustomStrings(filePath: string): Promise<void> {
   try {
-    let customStringsData: Record<string, any>
-
-    // Try to parse as JSON first
-    try {
-      customStringsData = JSON.parse(customStringsArg)
-    } catch {
-      // If JSON parsing fails, treat as file path
-      const fileContent = await fs.readFile(customStringsArg, "utf8")
-      customStringsData = JSON.parse(fileContent)
-    }
+    // 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) {
-    throw new Error(`Failed to load custom strings: ${error instanceof Error ? error.message : String(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)}`)
+    }
   }
 }
 

test/unit/node/cli.test.ts

@@ -349,21 +349,18 @@ describe("parser", () => {
     })
   })
 
-  it("should parse i18n flag", async () => {
-    // Test with JSON string
-    const jsonString = '{"WELCOME": "Custom Welcome", "LOGIN_TITLE": "My App"}'
-    const args = parse(["--i18n", jsonString])
+  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: jsonString,
+      i18n: "/path/to/custom-strings.json",
     })
   })
 
-  it("should parse i18n file paths and JSON", async () => {
-    // Test with valid JSON that looks like a file path
-    expect(() => parse(["--i18n", "/path/to/file.json"])).not.toThrow()
-    
-    // Test with JSON string (no validation at CLI level)
-    expect(() => parse(["--i18n", '{"valid": "json"}'])).not.toThrow()
+  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 () => {

test/unit/node/i18n.test.ts

@@ -0,0 +1,85 @@
+import { promises as fs } from "fs"
+import * as os from "os"
+import * as path from "path"
+import { loadCustomStrings } from "../../../src/node/i18n"
+
+describe("i18n", () => {
+  let tempDir: string
+  let validJsonFile: string
+  let invalidJsonFile: string
+  let nonExistentFile: string
+
+  beforeEach(async () => {
+    // Create temporary directory for test files
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "code-server-i18n-test-"))
+    
+    // Create test files
+    validJsonFile = path.join(tempDir, "valid.json")
+    invalidJsonFile = path.join(tempDir, "invalid.json")
+    nonExistentFile = path.join(tempDir, "does-not-exist.json")
+
+    // Write valid JSON file
+    await fs.writeFile(validJsonFile, JSON.stringify({
+      "WELCOME": "Custom Welcome",
+      "LOGIN_TITLE": "My Custom App",
+      "LOGIN_BELOW": "Please log in to continue"
+    }))
+
+    // Write invalid JSON file
+    await fs.writeFile(invalidJsonFile, '{"WELCOME": "Missing closing quote}')
+  })
+
+  afterEach(async () => {
+    // Clean up temporary directory
+    await fs.rmdir(tempDir, { recursive: true })
+  })
+
+  describe("loadCustomStrings", () => {
+    it("should load valid JSON file successfully", async () => {
+      // Should not throw an error
+      await expect(loadCustomStrings(validJsonFile)).resolves.toBeUndefined()
+    })
+
+    it("should throw clear error for non-existent file", async () => {
+      await expect(loadCustomStrings(nonExistentFile)).rejects.toThrow(
+        `Custom strings file not found: ${nonExistentFile}\nPlease ensure the file exists and is readable.`
+      )
+    })
+
+    it("should throw clear error for invalid JSON", async () => {
+      await expect(loadCustomStrings(invalidJsonFile)).rejects.toThrow(
+        `Invalid JSON in custom strings file: ${invalidJsonFile}`
+      )
+    })
+
+    it("should handle empty JSON object", async () => {
+      const emptyJsonFile = path.join(tempDir, "empty.json")
+      await fs.writeFile(emptyJsonFile, "{}")
+      
+      await expect(loadCustomStrings(emptyJsonFile)).resolves.toBeUndefined()
+    })
+
+    it("should handle nested JSON objects", async () => {
+      const nestedJsonFile = path.join(tempDir, "nested.json")
+      await fs.writeFile(nestedJsonFile, JSON.stringify({
+        "WELCOME": "Hello World",
+        "NESTED": {
+          "KEY": "Value"
+        }
+      }))
+      
+      await expect(loadCustomStrings(nestedJsonFile)).resolves.toBeUndefined()
+    })
+
+    it("should handle special characters and unicode", async () => {
+      const unicodeJsonFile = path.join(tempDir, "unicode.json")
+      await fs.writeFile(unicodeJsonFile, JSON.stringify({
+        "WELCOME": "欢迎来到 code-server",
+        "LOGIN_TITLE": "Willkommen bei {{app}}",
+        "SPECIAL": "Special chars: àáâãäåæçèéêë 🚀 ♠️ ∆"
+      }), "utf8")
+      
+      await expect(loadCustomStrings(unicodeJsonFile)).resolves.toBeUndefined()
+    })
+  })
+})