Scalar Dictionary Implementation Guide

Comprehensive guide to creating internationalized scalar dictionary files for type-safe translations in Akan.js applications.

Key Benefits

{app,lib}/

└── */lib/__scalar/

    └── <scalarName>/               # camelCase directory

        ├── <scalarName>.constant.ts  # model definition

        └── <scalarName>.dictionary.ts # translations

Translation Patterns

Type	Pattern	Example	Description
Model Metadata	`modelName / modelDesc`	modelName: ["User", "사용자"], modelDesc: ["User account", "사용자 계정"],	Required top-level translations for model identification
Field Translation	`fieldName / desc-fieldName`	username: ["Username", "사용자명"], "desc-username": ["Login identifier", "로그인 식별자"],	Field label followed by its description
Enum Translation	`enum-field-value / enumdesc-field-value`	"enum-status-active": ["Active", "활성"], "enumdesc-status-active": ["Active account", "활성 계정"],	Enum value label followed by its description

Required Structure

import { ModelDictionary } from "@akanjs/dictionary";

import type { YourModel } from "./your-model.constant";

const modelDictionary = {

  // Required metadata

  modelName: ["User", "사용자"],

  modelDesc: ["User account", "사용자 계정"],

  // Field translations

  username: ["Username", "사용자명"],

  "desc-username": ["Login identifier", "로그인 식별자"],

  // Enum translations

  "enum-status-active": ["Active", "활성"],

  "enumdesc-status-active": ["Active account", "활성 계정"],

  // Custom translations

  customLabel: ["Custom Text", "사용자 정의 텍스트"]

} satisfies ModelDictionary<YourModel>;

export const yourModelDictionary = modelDictionary;

Common Mistakes & Fixes

Wrong

username: ["Username", "사용자명"],

Correct

username: ["Username", "사용자명"],

"desc-username": ["User's login name", "로그인에 사용하는 이름"],

Wrong

"enum_status_active": ["Active", "활성"],

Correct

"enum-status-active": ["Active", "활성"],

"enumdesc-status-active": ["Account is active", "계정이 활성화됨"],

Wrong

const modelDictionary = {

  username: ["Username", "사용자명"],

  // ...

Correct

const modelDictionary = {

  modelName: ["User", "사용자"],

  modelDesc: ["User account", "사용자 계정"],

  // ...

Best Practices

Logical Order: Place model metadata first, followed by fields, enums, and custom translations
Clear Separators: Use comment blocks to organize sections
Consistent Terminology: Maintain uniform terminology across all translations
Type Safety: Always use satisfies ModelDictionary<YourModel> for validation
Naming Conventions: Follow kebab-case for prefixes (desc-, enum-, enumdesc-)

Validation Checklist

Complete Example

import { ModelDictionary } from "@akanjs/dictionary";

import type { User } from "./user.constant";

const modelDictionary = {

  modelName: ["User", "사용자"],

  modelDesc: ["System user account", "시스템 사용자 계정"],

  // ================ Model Fields ================ //

  username: ["Username", "사용자명"],

  "desc-username": ["Unique login identifier", "고유 로그인 식별자"],

  email: ["Email", "이메일"],

  "desc-email": ["Contact email address", "연락용 이메일 주소"],

  status: ["Status", "상태"],

  "desc-status": ["Account status", "계정 상태"],

  // ================ Model Fields ================ //

  // ================ Enums ================ //

  "enum-status-active": ["Active", "활성"],

  "enumdesc-status-active": ["Account is enabled", "계정이 활성화됨"],

  "enum-status-inactive": ["Inactive", "비활성"],

  "enumdesc-status-inactive": ["Account disabled", "계정이 비활성화됨"],

  // ================ Enums ================ //

  // ================ Custom ================ //

  profileTitle: ["User Profile", "사용자 프로필"],

  loginHistory: ["Login History", "로그인 기록"]

  // ================ Custom ================ //

} satisfies ModelDictionary<User>;

export const userDictionary = modelDictionary;

Released under the MIT License

Official Akan.js Consulting onAkansoft

System managed bybassman