Make proxy/API error messages locale-aware or configurable

[etwk]

Summary

API/proxy-facing error responses can currently return Chinese text to non-Chinese API clients. This is useful for Chinese users, but it creates an i18n mismatch for deployments serving English or other-language clients through OpenAI/Claude/Gemini-compatible APIs.

This is not asking to remove the Chinese messages. The request is to make the API-facing error language locale-aware or operator-configurable.

Current behavior

Some client-visible proxy errors are concrete Chinese strings in code/default data, for example:

• src/app/v1/_lib/proxy/errors.ts defines the all-providers-unavailable fallback message as Chinese.
• src/repository/error-rules.ts seeds DEFAULT_ERROR_RULES with overrideResponse.error.message values in Chinese.
• src/i18n/config.ts sets the app default locale to zh-CN, but API/proxy error responses do not appear to negotiate or select language separately.

Related context: #349 intentionally added preset Chinese return prompts for default client error rules. This issue is about making that behavior configurable or localized for API consumers.

Why this matters

For machine-facing compatible APIs, the caller may not be using the Web UI locale at all. A non-Chinese client can receive an OpenAI/Claude-compatible error body whose error.message is Chinese, even if the request has Accept-Language: en or the deployment operator wants English API errors.

This makes downstream logs, user-facing client errors, and automated integrations harder to understand in non-Chinese environments.

Expected behavior

There should be a supported way to choose the language for API/proxy error messages, while preserving the existing Chinese defaults for zh-CN users.

Possible approaches:

• Respect Accept-Language for API/proxy error responses when available.
• Add an operator setting/env var such as a default API error locale.
• Store default error-rule override messages as message keys or per-locale response templates instead of a single hard-coded language.
• Keep the response shape stable for OpenAI/Claude/Gemini-compatible clients.
• Preserve custom database error-rule overrides during default rule sync.

Example reproduction

1. Deploy a fresh instance.
2. Trigger a default proxy error or a default error-rule override, such as an all-providers-unavailable case or a prompt/model validation rule.
3. Send the request from a non-Chinese API client, optionally with Accept-Language: en.
4. Observe that the returned compatible API error body can contain a Chinese error.message.

Acceptance criteria

• Existing Chinese messages still work for Chinese locale/users.
• Non-Chinese API clients can receive English or configured-locale error messages without editing source code.
• Default error-rule sync does not overwrite operator/custom localized overrides unexpectedly.

[coderabbitai]

🔗 Related PRs

#544 - Fix #541: Add error rule for Codex reasoning effort mismatch [merged]
#547 - feat(error-rules): add Gemini non-streaming error rule [merged]
#597 - feat(usage-doc): update OpenCode config example with GPT-5.2 and Gemini v1beta [merged]
#954 - feat(i18n): add authenticated proxy format hints / 补充代理认证格式提示 [merged]
#1130 - release v0.7.4 [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Thank you for this well-researched feature suggestion. Your analysis is accurate, and I can add some concrete detail from the codebase that is directly relevant.

Verification of the described behavior

Your three cited locations all check out:

• src/app/v1/_lib/proxy/errors.ts:18 exports ALL_PROVIDERS_UNAVAILABLE_MESSAGE = "所有供应商暂时不可用，请稍后重试" as a hard-coded constant.
• src/repository/error-rules.ts:292-878 seeds DEFAULT_ERROR_RULES where every overrideResponse.error.message is a Chinese string.
• src/i18n/config.ts:13 sets defaultLocale: Locale = "zh-CN".

There are two additional hard-coded Chinese sites in the same proxy error path that are worth accounting for in any fix:

• src/app/v1/_lib/proxy/error-handler.ts:78-108 (getGenericProxyErrorFallbackMessage) returns Chinese fallback strings per status code (400/401/403/404/429/5xx...).
• src/app/v1/_lib/proxy/error-handler.ts:240 sets the catch-all client message to "代理请求发生未知错误".

Existing pattern that already solves part of this

The proxy path already has a working i18n mechanism for error responses — it just has not been extended to the sites above. The auth and rate-limit guards resolve the request locale and look up translated messages:

• src/app/v1/_lib/proxy/auth-guard.ts:12-18 defines getRequestLocale(), which calls next-intl/server's getLocale(). Per src/i18n/routing.ts:18-33, locale detection order is: NEXT_LOCALE cookie -> Accept-Language header -> default locale. So Accept-Language: en is already honored here.
• src/app/v1/_lib/proxy/rate-limit-guard.ts uses the same getLocale() + getErrorMessageServer(locale, ERROR_CODES.RATE_LIMIT_*) pattern (many call sites, e.g. lines 80-82, 113-115).
• src/lib/utils/error-messages.ts:122-211 provides the centralized ERROR_CODES enum and getErrorMessageServer(), which resolves translations via getTranslations({ locale, namespace: "errors" }).
• messages/{locale}/errors.json exists in all five locales (en, ja, ru, zh-CN, zh-TW); the PROXY_* and RATE_LIMIT_* keys are already translated across all of them.

So for ALL_PROVIDERS_UNAVAILABLE_MESSAGE and the error-handler.ts fallbacks, the infrastructure (locale resolution + translation lookup + per-locale message files) already exists and is proven on the proxy hot path. Extending it is largely a matter of routing those strings through getErrorMessageServer() instead of inlining them.

Implementation considerations

Error-rule overrides are the hard part. The errorRules.overrideResponse column is a plain jsonb blob (src/drizzle/schema.ts:688) with no locale dimension, and DEFAULT_ERROR_RULES stores fully-formed response objects including the literal message. As you noted, options here are to store message keys / per-locale templates instead of a single hard-coded string.

The default-rule sync already preserves custom overrides, but via isDefault, not locale. In syncDefaultErrorRules() (src/repository/error-rules.ts:895-980): rules with isDefault=false are skipped (lines 972-973), while rules still flagged isDefault=true have their overrideResponse overwritten (lines 949-970). This means an operator's edits are preserved today only if editing flips isDefault to false (see updateErrorRule at lines 233-246, which notes editing a default rule auto-sets isDefault=false). A localized-default design would need to preserve this behavior so re-syncing defaults does not clobber an operator's localized customizations.

A regex in the client-message redactor depends on the literal string. src/app/v1/_lib/proxy/client-error-message.ts:36 embeds ALL_PROVIDERS_UNAVAILABLE_MESSAGE into INTERNAL_ONLY_RE (used to suppress internal-only messages from client output). If that message becomes locale-dependent, this detection pattern (and any tests asserting on it) would need to track all localized variants or switch to a stable marker.

Response shape stability. None of the above needs to change the JSON shape returned to OpenAI/Claude/Gemini-compatible clients — error-handler.ts builds the override body generically (lines 377-384) and only the message string value would be localized.

In short: the locale-negotiation plumbing and translation files already exist and are already used for auth/rate-limit errors in the proxy path, so the bulk of this is feasible by reuse. The main design decision is the data model for errorRules defaults (literal strings vs. message keys / per-locale templates) and how the sync logic interacts with operator-localized overrides.

---

Automated response from Claude AI

[github-actions]

This issue has been automatically marked as stale because it has not had any activity in the last 30 days.

If this issue is still relevant:

• Please comment to keep it open
• Add any new information that might help resolve it

This issue will be automatically closed in 14 days if there is no further activity.