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.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
#!/usr/bin/env node
// Plan 79 D3 ratchet — untranslated user-visible copy.
//
// Counts string literals that a user can READ and that are not addressed by a
// translation key. Five shapes, because copy escapes into all five:
//
// 1. JSX text nodes <p>No applications yet</p>
// 2. JSX copy attributes <Input placeholder="Search apps" />
// 3. Toast / confirm arguments toast.error('Failed to save')
// 4. Copy keys in data objects { label: 'Applications' } <- sidebarItems.js
// 5. Inline alternatives {saving ? 'Saving…' : 'Save'} {`${n} services`}
//
// Shapes 4 and 5 look through the expression to the strings a user can end
// up reading: both arms of a ternary, the fallback of `a || 'Unknown'`, the
// right side of `ok && 'Ready'`, and the text of a template literal (its
// `${}` holes stand in as {{x}}). The CONDITION of a ternary is not read --
// `status === 'Running' ? ...` compares a value, it does not show one.
//
// Shape 4 is the one that usually escapes an extraction pass: a label sitting
// in a data file is still copy, and if it is resolved at module load it also
// never re-renders on a locale switch. It is counted so that converting those
// files is visible here.
//
// A literal is exempt when it is an argument of `t(...)` — that is the whole
// point of the migration — or when it does not look like prose (see isCopy).
//
// This is a ratchet, not a gate: the count may only go down. It is seeded
// BEFORE the migration starts (plan 76 rule 1: a migration without a ratchet
// regrows) so that a new page, or plan 68's Recipes surface, cannot add
// untranslated copy without failing `npm run lint`.
//
// Usage (from frontend/):
// node scripts/check-i18n-literals.mjs # check against the ceiling
// node scripts/check-i18n-literals.mjs --report # list the worst files
// node scripts/check-i18n-literals.mjs --report --file src/pages/Apps.jsx
// node scripts/check-i18n-literals.mjs --update # write the current count
import { execFileSync } from 'node:child_process';
import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
import { dirname, extname, join, relative, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { parse } from 'espree';
const here = dirname(fileURLToPath(import.meta.url));
const root = resolve(here, '..');
// `--root <dir>` points the census at another tree — an extension repo's own
// src/. Extensions ship UI with the same copy problem and none of them live
// under frontend/src, so without this the ratchet cannot see them at all.
// An extension repo runs this file from the host checkout rather than copying
// it, which is how the vendor shims drifted.
const rootArg = process.argv.includes('--root')
? process.argv[process.argv.indexOf('--root') + 1]
: null;
const srcDir = rootArg ? resolve(process.cwd(), rootArg) : resolve(root, 'src');
const ceilingFile = resolve(here, 'I18N_LITERAL_CEILING');
// Slack before the ceiling is considered stale. Larger than the style
// ratchet's 5 because this census starts in the thousands and a single page
// conversion moves it by dozens; smaller than a wave, so a finished wave still
// has to write its result down.
const STALE_SLACK = 50;
// Props whose value is read by a human. `title` is here even though it is
// sometimes a machine value — the false positives are excluded by isCopy.
const COPY_PROPS = new Set([
'label', 'placeholder', 'title', 'description', 'helpText', 'help',
'emptyText', 'emptyMessage', 'confirmText', 'cancelText', 'submitText',
'heading', 'subtitle', 'subheading', 'caption', 'hint', 'tooltip',
'alt', 'aria-label', 'aria-description', 'aria-placeholder',
'message', 'text', 'buttonText', 'actionLabel', 'header',
]);
// Object keys that carry copy in data files (sidebarItems.js, column defs,
// wizard step tables, validation maps).
const COPY_KEYS = new Set([
'label', 'title', 'description', 'placeholder', 'helpText', 'help',
'emptyText', 'emptyMessage', 'confirmText', 'cancelText', 'submitText',
'heading', 'subtitle', 'subheading', 'caption', 'hint', 'tooltip',
'message', 'buttonText', 'actionLabel', 'header', 'summary',
]);
// Callees whose string arguments are shown to a user.
const COPY_CALLS = new Set([
'success', 'error', 'info', 'warning', 'warn', 'message', 'loading',
'showToast', 'toast', 'notify', 'confirm', 'alert',
]);
const TOAST_OBJECTS = new Set(['toast', 'toasts', 'sonner', 'notifications']);
// Callees whose arguments go to the panel's error tracker, never to a screen:
// `api.reportClientError({ message: err?.message || 'Unknown error' })`. That
// English is for whoever reads the server log, and translating it would make
// reports arrive in each viewer's language.
const TELEMETRY_CALLS = new Set(['reportClientError']);
// Directories that hold no user-facing copy, or hold it deliberately.
const SKIP_DIRS = new Set(['__tests__', '__mocks__', 'node_modules']);
const SKIP_FILE = /\.(test|spec|stories)\.[jt]sx?$/;
// The i18n plumbing itself: locale JSON loaders, the manifest, the format
// door's own fallback strings.
const SKIP_PATH = /^(i18n\/|data\/bundledThemes)/;
// A dotted, lowercase-namespaced path: `nav.dashboard`, `common.actions.save`.
const TRANSLATION_KEY = /^[a-z][a-zA-Z0-9]*(\.[a-zA-Z0-9_]+)+$/;
/**
* Does this literal read as prose a user would notice?
*
* Deliberately generous on the exclusion side: a ratchet that flags
* `className="btn"` trains people to ignore it. The rule is "contains a space,
* or is a capitalised word of 3+ characters" — which keeps "Save" and
* "No results found" and drops "sm", "btn-primary", "app_id", "/api/v1/apps".
*/
function isCopy(raw) {
const value = String(raw).trim();
if (value.length < 2) return false;
if (!/[A-Za-z]/.test(value)) return false; // numbers, symbols, spacers
if (/^https?:\/\//.test(value)) return false; // URLs
// routes, selectors, anchors -- but ". It takes a minute." is the tail of
// a sentence split around an element: a dot then a space is never a selector.
if (/^[/#.]/.test(value) && !/^[.,;:]\s/.test(value)) return false;
if (/^[a-z0-9]+([-_.:][a-z0-9]+)+$/.test(value)) return false; // ids, css classes, keys
if (/^[A-Z0-9]+(_[A-Z0-9]+)*$/.test(value)) return false; // CONSTANT_CASE
if (/^[a-z]+$/.test(value)) return false; // bare lowercase token: 'sm', 'primary'
if (/^\{\{.*\}\}$/.test(value)) return false; // interpolation placeholder
if (/^[a-z][a-zA-Z0-9]*$/.test(value)) return false; // camelCase identifier
return /\s/.test(value) || /^[A-Z].{2,}/.test(value);
}
function walkFiles(dir) {
return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
if (entry.isDirectory()) {
return SKIP_DIRS.has(entry.name) ? [] : walkFiles(join(dir, entry.name));
}
const ext = extname(entry.name);
if (ext !== '.js' && ext !== '.jsx') return [];
if (SKIP_FILE.test(entry.name)) return [];
return [join(dir, entry.name)];
});
}
function calleeName(node) {
if (!node) return null;
if (node.type === 'Identifier') return node.name;
if (node.type === 'MemberExpression' && !node.computed) {
return node.property?.name ?? null;
}
return null;
}
function calleeObject(node) {
if (node?.type === 'MemberExpression' && node.object?.type === 'Identifier') {
return node.object.name;
}
return null;
}
/** Is this a translation call — `t(...)`, `i18n.t(...)`, `props.t(...)`? */
function isTranslationCall(node) {
if (node.type !== 'CallExpression') return false;
return calleeName(node.callee) === 't';
}
function attributeName(attr) {
const name = attr.name;
if (!name) return null;
return name.type === 'JSXNamespacedName'
? `${name.namespace.name}:${name.name.name}`
: name.name;
}
function propertyKey(prop) {
if (prop.computed) return null;
const key = prop.key;
if (!key) return null;
return key.type === 'Identifier' ? key.name : (typeof key.value === 'string' ? key.value : null);
}
/** Every string literal reachable from a node, ignoring nested translation calls. */
function collectStrings(node, out) {
if (!node || typeof node !== 'object') return;
if (Array.isArray(node)) {
for (const child of node) collectStrings(child, out);
return;
}
if (!node.type) return;
if (isTranslationCall(node)) return;
// Stop at nested JSX. A copy prop holding an element —
// `message={<span>… <a rel="noopener noreferrer">…</a></span>}` — must not
// have that element's OWN attributes counted: `rel` is not copy, and the
// walk reaches the element on its own terms anyway. Counting them made the
// ratchet unreachable on correct code.
if (node.type === 'JSXElement' || node.type === 'JSXFragment') return;
if (node.type === 'Literal' && typeof node.value === 'string') {
out.push(node);
return;
}
if (node.type === 'TemplateLiteral') {
out.push({ loc: node.loc, value: templateText(node) });
for (const expr of node.expressions) collectStrings(expr, out);
return;
}
for (const key of Object.keys(node)) {
if (key === 'type' || key === 'loc' || key === 'range' || key === 'parent') continue;
collectStrings(node[key], out);
}
}
// A template literal read as one sentence: `${n} services` is the copy
// "{{x}} services", not the lone word "services" (which isCopy would drop as
// a bare lowercase token).
const HOLE = '{{x}}';
// A number and its unit -- `${ms} ms`, `${pct}%`, `${size} GB` -- is a
// measurement, not a sentence: the unit symbol is the same in every locale
// the panel ships. Only bare SI/byte symbols qualify; a unit spelled as a
// word ("{{x}} days", "{{x}}% cpu") is still copy.
const UNIT_ONLY = /^(ms|s|%|[KMGT]i?B|px)$/;
function templateText(node) {
return node.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw).join(HOLE);
}
/**
* The strings a user can end up READING out of an expression, without the
* ones it merely computes with. Ternaries yield both arms (never the test);
* `a || 'x'` and `a ?? 'x'` yield both sides; `ok && 'x'` only the right one;
* a template literal yields its text. Calls (t() included), member reads and
* JSX stop the walk -- JSX is visited on its own terms.
*/
function leafStrings(node, out) {
if (!node) return;
switch (node.type) {
case 'Literal':
if (typeof node.value === 'string') out.push(node);
return;
case 'TemplateLiteral':
out.push({ loc: node.loc, value: templateText(node) });
for (const expr of node.expressions) leafStrings(expr, out);
return;
case 'ConditionalExpression':
leafStrings(node.consequent, out);
leafStrings(node.alternate, out);
return;
case 'LogicalExpression':
if (node.operator !== '&&') leafStrings(node.left, out);
leafStrings(node.right, out);
return;
default:
return;
}
}
const CODE_TAGS = new Set(['code', 'pre']);
/**
* Is this child of a <code>/<pre> the sample itself -- a log line,
* `S3_BUCKET=${bucket}` -- rather than a placeholder shown in its place?
* Only the value (a literal, or `cond && literal`) is exempt; a fallback such
* as `{logs || 'Waiting for logs…'}` or a ternary arm is still copy.
*/
function isCodeSample(element, expression) {
if (!CODE_TAGS.has(element.openingElement?.name?.name)) return false;
const value = expression.type === 'LogicalExpression' && expression.operator === '&&'
? expression.right
: expression;
return value.type === 'Literal' || value.type === 'TemplateLiteral';
}
const INLINE_SHAPES = new Set(['ConditionalExpression', 'LogicalExpression', 'TemplateLiteral', 'Literal']);
function censusFile(path, rel) {
const source = readFileSync(path, 'utf8');
let ast;
try {
ast = parse(source, {
ecmaVersion: 'latest',
sourceType: 'module',
ecmaFeatures: { jsx: true },
loc: true,
});
} catch (error) {
// A file this script cannot parse cannot be censused; failing loudly
// beats silently dropping its literals out of the ceiling.
throw new Error(`${rel}: parse failed — ${error.message}`);
}
const hits = [];
// Properties exempted because the object also declares a translation key
// for them: `{ labelKey: 'nav.apps', label: 'Applications' }`. The label is
// the English default for that key, resolved at render -- not stray copy.
const keyed = new WeakSet();
const record = (node, kind, value) => {
const text = String(value).trim().replace(/\s+/g, ' ');
// `${a} ${b}` is all holes: nothing in it is copy of its own.
if (text.includes(HOLE) && !/[A-Za-z]{2,}/.test(text.split(HOLE).join(' '))) return;
if (text.includes(HOLE) && UNIT_ONLY.test(text.split(HOLE).join('').trim())) return;
if (!isCopy(text)) return;
hits.push({ line: node.loc?.start.line ?? 0, kind, text: text.slice(0, 70) });
};
const visit = (node) => {
if (!node || typeof node !== 'object') return;
if (Array.isArray(node)) {
for (const child of node) visit(child);
return;
}
if (!node.type) return;
// 0. Translated already — the literal inside `t('k', 'Default')` is the
// source of English, not an untranslated string. Do not descend.
if (isTranslationCall(node)) return;
switch (node.type) {
// 1. JSX text nodes.
case 'JSXText':
record(node, 'text', node.value);
break;
// 5. Inline alternatives rendered as a child:
// {saving ? 'Saving…' : 'Save'} {`${n} services`} {err || 'Failed'}
// Attribute values are not children; shape 2 owns those.
case 'JSXElement':
case 'JSXFragment':
for (const child of node.children) {
if (child.type !== 'JSXExpressionContainer') continue;
if (!INLINE_SHAPES.has(child.expression?.type)) continue;
if (isCodeSample(node, child.expression)) continue;
const strings = [];
leafStrings(child.expression, strings);
for (const literal of strings) record(literal, 'expr', literal.value);
}
break;
// 2. JSX copy attributes.
case 'JSXAttribute': {
const name = attributeName(node);
if (name && COPY_PROPS.has(name) && node.value) {
if (node.value.type === 'Literal' && typeof node.value.value === 'string') {
record(node, 'prop', node.value.value);
} else if (node.value.type === 'JSXExpressionContainer') {
const strings = [];
// A ternary's test is a comparison, not copy:
// title={status === 'Running' ? t(...) : t(...)}.
if (INLINE_SHAPES.has(node.value.expression?.type)) {
leafStrings(node.value.expression, strings);
} else {
collectStrings(node.value.expression, strings);
}
for (const literal of strings) record(literal, 'prop', literal.value);
}
// Value handled; keep descending for nested JSX only.
if (node.value.type === 'JSXExpressionContainer') break;
return;
}
break;
}
// 3. Toast / confirm arguments.
case 'CallExpression': {
const name = calleeName(node.callee);
if (TELEMETRY_CALLS.has(name)) return;
const object = calleeObject(node.callee);
const isCopyCall = name && COPY_CALLS.has(name)
&& (object === null || TOAST_OBJECTS.has(object) || name === 'confirm');
if (isCopyCall) {
for (const arg of node.arguments) {
const strings = [];
collectStrings(arg, strings);
for (const literal of strings) record(literal, 'toast', literal.value);
}
for (const arg of node.arguments) visit(arg);
return;
}
break;
}
// Declarative key pairs, marked before their properties are seen.
case 'ObjectExpression': {
const named = new Map();
for (const property of node.properties) {
if (property.type !== 'Property' || property.computed) continue;
named.set(property.key?.name || property.key?.value, property);
}
for (const [name, property] of named) {
if (!name || !name.endsWith('Key')) continue;
if (property.value?.type !== 'Literal') continue;
if (!TRANSLATION_KEY.test(String(property.value.value))) continue;
const sibling = named.get(name.slice(0, -3));
if (sibling) keyed.add(sibling);
}
break;
}
// 4. Copy keys in data objects.
case 'Property': {
if (keyed.has(node)) return;
const key = propertyKey(node);
if (key && COPY_KEYS.has(key) && node.value?.type === 'Literal'
&& typeof node.value.value === 'string') {
record(node, 'data', node.value.value);
return;
}
// { label: busy ? 'Saving…' : 'Save' }, { title: `Delete ${name}` }
if (key && COPY_KEYS.has(key) && INLINE_SHAPES.has(node.value?.type)) {
const strings = [];
leafStrings(node.value, strings);
for (const literal of strings) record(literal, 'data', literal.value);
// Keep descending: an arm may hold JSX or a t() call.
}
break;
}
default:
break;
}
for (const key of Object.keys(node)) {
if (key === 'type' || key === 'loc' || key === 'range' || key === 'parent') continue;
visit(node[key]);
}
};
visit(ast);
return hits;
}
/**
* Extension copies under plugins/ that git does not track: a sibling repo's
* build dropped into a dev checkout. They are censused in their own repo
* (`--root`), and counting them here made the host number depend on which
* extensions a machine happens to have installed -- a fresh clone could never
* reach a ceiling written on a dev box. Null when git is unavailable (release
* tarball): then everything on disk is counted.
*/
function trackedPluginDirs() {
if (rootArg) return null;
try {
const out = execFileSync('git', ['ls-files', '--', 'plugins'], {
cwd: srcDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
});
return new Set(out.split('\n').filter(Boolean).map((line) => line.split('/')[1]));
} catch {
return null;
}
}
export function census() {
const byFile = new Map();
const tracked = trackedPluginDirs();
for (const path of walkFiles(srcDir)) {
const rel = relative(srcDir, path).replaceAll('\\', '/');
if (SKIP_PATH.test(rel)) continue;
const parts = rel.split('/');
if (tracked && parts[0] === 'plugins' && parts.length > 2 && !tracked.has(parts[1])) continue;
const hits = censusFile(path, rel);
if (hits.length) byFile.set(rel, hits);
}
return byFile;
}
const byFile = census();
const count = [...byFile.values()].reduce((total, hits) => total + hits.length, 0);
if (process.argv.includes('--update')) {
if (rootArg) {
console.error('--update writes the HOST ceiling; refusing to do that from --root.');
process.exit(2);
}
writeFileSync(ceilingFile, `${count}\n`);
console.log(`i18n literal ceiling updated to ${count}`);
process.exit(0);
}
if (process.argv.includes('--report')) {
const fileArg = process.argv[process.argv.indexOf('--file') + 1];
if (process.argv.includes('--file') && fileArg) {
const key = fileArg.replace(/\\/g, '/').replace(/^(frontend\/)?src\//, '');
const hits = byFile.get(key) || [];
for (const hit of hits) {
console.log(` ${String(hit.line).padStart(5)} ${hit.kind.padEnd(5)} ${hit.text}`);
}
console.log(`\n${key}: ${hits.length}`);
process.exit(0);
}
const rows = [...byFile].sort((a, b) => b[1].length - a[1].length).slice(0, 40);
for (const [file, hits] of rows) {
const kinds = hits.reduce((acc, hit) => {
acc[hit.kind] = (acc[hit.kind] || 0) + 1;
return acc;
}, {});
const detail = Object.entries(kinds).map(([k, v]) => `${k}:${v}`).join(' ');
console.log(` ${String(hits.length).padStart(4)} ${file.padEnd(58)} ${detail}`);
}
console.log(`\ntotal: ${count} untranslated literals in ${byFile.size} files`);
process.exit(0);
}
const ceiling = Number(readFileSync(ceilingFile, 'utf8').trim());
if (count > ceiling) {
const worst = [...byFile].sort((a, b) => b[1].length - a[1].length).slice(0, 5);
console.error('\ni18n literal check failed:\n');
console.error(` ${count} untranslated user-visible literals; the ceiling is ${ceiling}.`);
console.error(' New copy must go through a translation key:\n');
console.error(" import { useTranslation } from 'react-i18next';");
console.error(' const { t } = useTranslation();');
console.error(" <h2>{t('apps.empty.title', 'No applications yet')}</h2>\n");
console.error(' The second argument is the English default — it is what `en.json` is');
console.error(' generated from, so it is never wrong to include it.\n');
for (const [file, hits] of worst) {
console.error(` ${String(hits.length).padStart(4)} ${file}`);
}
console.error('\n node scripts/check-i18n-literals.mjs --report --file <path> to see them\n');
process.exit(1);
}
if (ceiling - count > STALE_SLACK) {
console.error(`\ni18n literal ceiling is ${ceiling} but only ${count} remain; run`);
console.error(' node scripts/check-i18n-literals.mjs --update\n');
process.exit(1);
}
console.log(`✓ i18n literals: ${count} untranslated literals remain ratcheted (ceiling ${ceiling}).`);