Scalar Dictionary Implementation Guide

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

Key Benefits

End-to-end type safety
Consistent terminology across applications
Automatic documentation generation
Multi-language support (EN/KO)

File Structure

{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

1import { ModelDictionary } from "@akanjs/dictionary";
2import type { YourModel } from "./your-model.constant";
3
4const modelDictionary = {
5  // Required metadata
6  modelName: ["User", "사용자"],
7  modelDesc: ["User account", "사용자 계정"],
8  
9  // Field translations
10  username: ["Username", "사용자명"],
11  "desc-username": ["Login identifier", "로그인 식별자"],
12  
13  // Enum translations
14  "enum-status-active": ["Active", "활성"],
15  "enumdesc-status-active": ["Active account", "활성 계정"],
16  
17  // Custom translations
18  customLabel: ["Custom Text", "사용자 정의 텍스트"]
19} satisfies ModelDictionary<YourModel>;
20
21export const yourModelDictionary = modelDictionary;

Common Mistakes & Fixes

Missing field description

Wrong

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

Correct

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

Incorrect enum naming

Wrong

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

Correct

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

Missing model metadata

Wrong

1const modelDictionary = {
2  username: ["Username", "사용자명"],
3  // ...

Correct

1const modelDictionary = {
2  modelName: ["User", "사용자"],
3  modelDesc: ["User account", "사용자 계정"],
4  // ...

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

All model fields have translations
All enum values have translations
modelName and modelDesc are defined
Field descriptions use desc- prefix
Enum descriptions use enumdesc- prefix
satisfies ModelDictionary<YourModel> is included
Export name matches model name

Complete Example

1import { ModelDictionary } from "@akanjs/dictionary";
2import type { User } from "./user.constant";
3
4const modelDictionary = {
5  modelName: ["User", "사용자"],
6  modelDesc: ["System user account", "시스템 사용자 계정"],
7
8  // ================ Model Fields ================ //
9  username: ["Username", "사용자명"],
10  "desc-username": ["Unique login identifier", "고유 로그인 식별자"],
11
12  email: ["Email", "이메일"],
13  "desc-email": ["Contact email address", "연락용 이메일 주소"],
14
15  status: ["Status", "상태"],
16  "desc-status": ["Account status", "계정 상태"],
17  // ================ Model Fields ================ //
18
19  // ================ Enums ================ //
20  "enum-status-active": ["Active", "활성"],
21  "enumdesc-status-active": ["Account is enabled", "계정이 활성화됨"],
22
23  "enum-status-inactive": ["Inactive", "비활성"],
24  "enumdesc-status-inactive": ["Account disabled", "계정이 비활성화됨"],
25  // ================ Enums ================ //
26
27  // ================ Custom ================ //
28  profileTitle: ["User Profile", "사용자 프로필"],
29  loginHistory: ["Login History", "로그인 기록"]
30  // ================ Custom ================ //
31} satisfies ModelDictionary<User>;
32
33export const userDictionary = modelDictionary;

Quick Start

Released under the MIT License

Official Akan.js Consulting onAkansoft

System managed bybassman

Docs

Scalar Dictionary Implementation Guide

Key Benefits

File Structure

Missing field description

Incorrect enum naming

Missing model metadata