Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

Translate the common server error codes

Juan Denise018e78d29e2
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index 09ed0a7a..ec85fa00 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -8283,6 +8283,9 @@
}
},
"errors": {
+ "agent": {
+ "offline": "The server's agent is offline. Start the agent on that server, then try again."
+ },
"auth": {
"accountDeactivated": "Account is deactivated",
"emailRegistered": "Email already registered",
@@ -8296,6 +8299,27 @@
"passwordTooShort": "Password must be at least 8 characters",
"registrationDisabled": "Registration is disabled",
"usernameTaken": "Username already taken"
+ },
+ "conflict": {
+ "domainExists": "Domain already exists"
+ },
+ "notFound": {
+ "backup": "Backup not found",
+ "configCheckpoint": "Config checkpoint not found",
+ "database": "Database not found",
+ "deployment": "Deployment not found",
+ "domain": "Domain not found",
+ "server": "Server not found",
+ "service": "Service not found",
+ "snapshot": "Snapshot not found",
+ "template": "Template not found",
+ "user": "User not found"
+ },
+ "permission": {
+ "denied": "You don't have permission to do this. Ask an admin for access."
+ },
+ "validation": {
+ "required": "{{field}} is required"
}
},
"git": {
diff --git a/frontend/src/i18n/locales/es.json b/frontend/src/i18n/locales/es.json
index 1a13f8b4..d709e938 100644
--- a/frontend/src/i18n/locales/es.json
+++ b/frontend/src/i18n/locales/es.json
@@ -6881,6 +6881,9 @@
}
},
"errors": {
+ "agent": {
+ "offline": "El agente del servidor está desconectado. Inícialo en ese servidor y vuelve a intentarlo."
+ },
"auth": {
"accountDeactivated": "La cuenta está desactivada",
"emailRegistered": "Ese correo ya está registrado",
@@ -6894,6 +6897,27 @@
"passwordTooShort": "La contraseña debe tener al menos 8 caracteres",
"registrationDisabled": "El registro está desactivado",
"usernameTaken": "Ese nombre de usuario ya está en uso"
+ },
+ "conflict": {
+ "domainExists": "El dominio ya existe"
+ },
+ "notFound": {
+ "backup": "No se encontró la copia de seguridad",
+ "configCheckpoint": "No se encontró el punto de control de configuración",
+ "database": "No se encontró la base de datos",
+ "deployment": "No se encontró el despliegue",
+ "domain": "No se encontró el dominio",
+ "server": "No se encontró el servidor",
+ "service": "No se encontró el servicio",
+ "snapshot": "No se encontró la instantánea",
+ "template": "No se encontró la plantilla",
+ "user": "No se encontró el usuario"
+ },
+ "permission": {
+ "denied": "No tienes permiso para hacer esto. Pide acceso a un administrador."
+ },
+ "validation": {
+ "required": "{{field}} es obligatorio"
}
},
"git": {
diff --git a/frontend/src/services/api/__tests__/errorCodes.test.mjs b/frontend/src/services/api/__tests__/errorCodes.test.mjs
new file mode 100644
index 00000000..b54b1e86
--- /dev/null
+++ b/frontend/src/services/api/__tests__/errorCodes.test.mjs
@@ -0,0 +1,38 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import i18next from 'i18next';
+import { translateServerError } from '../errorCodes.js';
+
+// An empty English bundle makes every t() return its inline default, so these
+// assertions read the registry's English: the same text en.json is built from.
+await i18next.init({ lng: 'en', resources: { en: { translation: {} } } });
+
+test('a fixed-message code replaces the server text', () => {
+ assert.equal(translateServerError('not_found.service', 'Service not found'), 'Service not found');
+ assert.equal(
+ translateServerError('permission.denied', 'whatever the server said'),
+ "You don't have permission to do this. Ask an admin for access.");
+});
+
+test("the agent dispatcher's AGENT_OFFLINE means the same as agent.offline", () => {
+ assert.equal(
+ translateServerError('AGENT_OFFLINE', 'Agent not connected'),
+ translateServerError('agent.offline', 'x'));
+});
+
+test('an unknown or prose-carrying code falls back to the server text', () => {
+ assert.equal(translateServerError('not_found', 'Monitor not found'), 'Monitor not found');
+ assert.equal(translateServerError('permission_denied', 'Path not allowed'), 'Path not allowed');
+ assert.equal(translateServerError(null, 'Plain text'), 'Plain text');
+});
+
+test('codes that name something need details, else keep the server text', () => {
+ assert.equal(translateServerError('validation.required', 'name is required'), 'name is required');
+ assert.equal(
+ translateServerError('validation.required', 'x', { field: 'name' }), 'name is required');
+ assert.equal(
+ translateServerError('conflict.exists', 'x', { resource: 'domain' }), 'Domain already exists');
+ assert.equal(
+ translateServerError('conflict.exists', 'Widget already exists', { resource: 'widget' }),
+ 'Widget already exists');
+});
diff --git a/frontend/src/services/api/errorCodes.js b/frontend/src/services/api/errorCodes.js
index a8600c53..9cb36c13 100644
--- a/frontend/src/services/api/errorCodes.js
+++ b/frontend/src/services/api/errorCodes.js
@@ -23,12 +23,25 @@ import { t } from '../../i18n/t.js';
* else falls through to the server's English, which is exactly today's
* behaviour.
*
- * WHY ONLY AUTH CODES SO FAR: plan 76 §C measured 23 sites that pick an HTTP
- * status by grepping their own error prose (`403 if 'denied' in error else
- * 400`). Until those services raise typed errors, translating that prose would
- * turn those 403s into 400s. The auth and onboarding routes carry codes today;
- * the rest waits on plan 76 milestone C rather than shipping a silent status
- * regression.
+ * WHICH CODES: plan 76 §C's 23 status-from-prose sites are gone (the status
+ * sniffing ratchet is at 0), so translating a message can no longer change a
+ * status. Beyond auth, plan 88 §C added the common families, each minted by a
+ * factory in `backend/app/exceptions.py` with ONE fixed message per code:
+ *
+ * not_found.<resource> "<Resource> not found"
+ * validation.required "<field> is required" (details.field)
+ * permission.denied generic "no permission" text
+ * conflict.exists "<Resource> already exists" (details.resource)
+ * agent.offline the agent is not connected
+ *
+ * A code is only listed here when its message is fixed. The class defaults
+ * (`not_found`, `validation_error`, `permission_denied`, `conflict`) carry
+ * per-call prose, so they deliberately stay untranslated: swapping them for a
+ * generic sentence would drop the specifics the server wrote.
+ *
+ * `details` (the body's `details` object) fills the two codes whose message
+ * names something. Without it they fall back to the server's English, so a
+ * caller that passes only (code, message) keeps today's behaviour.
*/
function translatedServerErrors() {
return {
@@ -56,14 +69,60 @@ function translatedServerErrors() {
'errors.auth.invitationInvalid', 'Invalid or expired invitation'),
'auth.link_invalid': t(
'errors.auth.linkInvalid', 'Invalid or expired link'),
+
+ // One literal per resource kind, so each is a key a translator can see
+ // (and so a language with grammatical gender can agree per noun).
+ 'not_found.service': t('errors.notFound.service', 'Service not found'),
+ 'not_found.server': t('errors.notFound.server', 'Server not found'),
+ 'not_found.domain': t('errors.notFound.domain', 'Domain not found'),
+ 'not_found.database': t('errors.notFound.database', 'Database not found'),
+ 'not_found.backup': t('errors.notFound.backup', 'Backup not found'),
+ 'not_found.snapshot': t('errors.notFound.snapshot', 'Snapshot not found'),
+ 'not_found.config_checkpoint': t(
+ 'errors.notFound.configCheckpoint', 'Config checkpoint not found'),
+ 'not_found.deployment': t('errors.notFound.deployment', 'Deployment not found'),
+ 'not_found.template': t('errors.notFound.template', 'Template not found'),
+ 'not_found.user': t('errors.notFound.user', 'User not found'),
+
+ 'permission.denied': t(
+ 'errors.permission.denied',
+ "You don't have permission to do this. Ask an admin for access."),
+
+ 'agent.offline': agentOffline(),
+ // The agent dispatcher's own result code. Command results reach the
+ // client verbatim on some routes, and its meaning is the same.
+ AGENT_OFFLINE: agentOffline(),
};
}
-export function translateServerError(code, serverMessage) {
+function agentOffline() {
+ return t(
+ 'errors.agent.offline',
+ "The server's agent is offline. Start the agent on that server, then try again.");
+}
+
+/** Codes whose message names something carried in the body's `details`. */
+function detailedServerError(code, details) {
+ if (!details || typeof details !== 'object') return undefined;
+ if (code === 'validation.required' && typeof details.field === 'string') {
+ return t('errors.validation.required', '{{field}} is required', { field: details.field });
+ }
+ if (code === 'conflict.exists') {
+ const exists = {
+ domain: t('errors.conflict.domainExists', 'Domain already exists'),
+ };
+ return exists[details.resource];
+ }
+ return undefined;
+}
+
+export function translateServerError(code, serverMessage, details) {
if (!code || typeof code !== 'string') return serverMessage;
// Built per call, not at module load: a table resolved at import would
// freeze the language of the session's first paint.
- return translatedServerErrors()[code] ?? serverMessage;
+ return translatedServerErrors()[code]
+ ?? detailedServerError(code, details)
+ ?? serverMessage;
}
export default translateServerError;