@atzentis/edu-locales

Type-safe i18n locale packs for @atzentis/edu-react and @atzentis/edu-expo.

Covers 12 educational domains in English (EN), German (DE), and Greek (EL).

Installation

npm install @atzentis/edu-locales
# or
bun add @atzentis/edu-locales

Zero runtime dependencies. Tree-shakeable ESM.

Convention: Flat SCREAMING_SNAKE Keys

All keys use SCREAMING_SNAKE_CASE and are globally unique across the entire locale object. The aggregate EduLocalization type is a flat TypeScript intersection — no nested namespaces.

Keys are disambiguated by a domain prefix:

| Domain prefix | Example keys | |---|---| | (none) — universal labels | CANCEL, SAVE, LOADING, ERROR | | TOOLS_ | TOOLS_TITLE, TOOLS_EXECUTE, TOOLS_NO_RESULTS | | TUTOR_ | TUTOR_TITLE, TUTOR_SEND, TUTOR_WELCOME | | SPACES_ | SPACES_TITLE, SPACES_CREATE, SPACES_EMPTY | | MC_ | MC_TITLE, MC_OVERVIEW, MC_PENDING_SUBMISSIONS | | SM_ | SM_FLASHCARDS_TITLE, SM_QUIZ_TITLE, SM_UNDO | | ANNOTATION_ | ANNOTATION_TITLE, ANNOTATION_ADD_COMMENT | | EXAMINER_ | EXAMINER_TITLE, EXAMINER_START_GRADING | | EXAMS_ | EXAMS_TITLE, EXAMS_CREATE, EXAMS_PASSED | | GRADING_ | GRADING_TITLE, GRADING_FINAL, GRADING_OUT_OF | | A11Y_ | A11Y_TITLE, A11Y_TTS, A11Y_TRANSLATE_TO | | ANALYTICS_ | ANALYTICS_TITLE, ANALYTICS_USAGE_TITLE |

Usage

Import the full locale

import en from "@atzentis/edu-locales/en";
import de from "@atzentis/edu-locales/de";
import el from "@atzentis/edu-locales/el";

console.log(en.TOOLS_EXECUTE);       // "Execute"
console.log(de.GRADING_FINAL);       // "Abschlussnote"
console.log(el.EXAMS_PASSED);        // "Επιτυχία"

TypeScript — typed access

import type { EduLocalization } from "@atzentis/edu-locales";
import en from "@atzentis/edu-locales/en";

const locale: EduLocalization = en;

// Type-safe flat key access
const label = locale.GRADING_OUT_OF;
// => "Grade: {{grade}} / {{max}}"

Interpolation

String values use {{placeholder}} tokens. Substitute with your i18n helper:

function t(template: string, vars: Record<string, string | number>): string {
  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => String(vars[key] ?? key));
}

t(en.GRADING_OUT_OF, { grade: 18, max: 20 });
// => "Grade: 18 / 20"

t(de.EXAMS_DURATION, { duration: 90 });
// => "Dauer: 90 Min."

React i18next

import en from "@atzentis/edu-locales/en";

i18n.init({
  resources: { en: { translation: en } },
  lng: "en",
});

// In component:
// t("GRADING_FINAL") => "Final Grade"

Tree-shaking — import only what you need

// Only loads the EN bundle (~10 KB)
import en from "@atzentis/edu-locales/en";

The 12 Domains

| Key prefix | Interface | Description | |---|---|---| | (no prefix) | CommonKeys | Universal UI labels (CANCEL, SAVE, LOADING, …) | | TOOLS_ | ToolsKeys | AI tool execution labels and errors | | TUTOR_ | TutorKeys | AI tutor chat labels and accessibility strings | | SPACES_ | SpacesKeys | Learning space CRUD and sidekick announcements | | MC_ | MissionControlKeys | Dashboard overview and alert labels | | SM_ | SmartModulesKeys | Flashcard, quiz, and whiteboard labels | | ANNOTATION_ | AnnotationKeys | Highlight, comment, voice note, video annotation | | EXAMINER_ | ExaminerKeys | Grading stages, scoring, and report labels | | EXAMS_ | ExamsKeys | Exam catalog, scheduling, and submission labels | | GRADING_ | GradingKeys | Quiz, essay, speaking, and final grade labels | | A11Y_ | AccessibilityKeys | TTS, dictionary, and translation labels | | ANALYTICS_ | AnalyticsKeys | Usage, engagement, and ROI metric labels |

Grading System Notes

• Greek system: 0–20 scale, passing grade >= 10. Panhellenic exams (Πανελλήνιες) for Grade 12 only.
• German system: 1.0–6.0 scale (1.0 = best), passing grade <= 4.0. MSA at Grade 10, Abitur at Grade 12.

Locale strings are system-agnostic. Grade values and formatting are handled by the host application.

Type Architecture

Each domain has a {Domain}Keys interface in src/types/{domain}.types.ts. The aggregate is defined as a flat TypeScript intersection:

export type EduLocalization = AccessibilityKeys &
  AnalyticsKeys &
  AnnotationKeys &
  CommonKeys &
  ExaminerKeys &
  ExamsKeys &
  GradingKeys &
  MissionControlKeys &
  SmartModulesKeys &
  SpacesKeys &
  ToolsKeys &
  TutorKeys;

Because every key is globally unique, this intersection is collision-free and the TS compiler enforces completeness of every locale pack via the : EduLocalization annotation on each locale index file.

Adding a New Locale

1. Create src/{code}/ directory with one file per domain (e.g. src/fr/common.ts).
2. Each file exports export const {domainCamel}: {Domain}Keys = { ... }.
3. Create src/{code}/index.ts combining all 12 domains:

   const fr: EduLocalization = { ...common, ...tools, /* ... */ };
   export default fr;

4. Add the entry to tsup.config.ts and the exports map in package.json.
5. Run bunx tsc --noEmit — missing or mistyped keys surface as compile errors.
6. Run bunx vitest run — parity tests confirm key-set equality with EN.

License

MIT — Atzentis <[email protected]>