Localized DB Columns

When you need to store multilingual values in the database, you can use locale-specific columns like name, name_ko, name_en, or a locale map like name: { ko: "...", en: "..." }. Sonamu automatically selects the appropriate value for the current locale using the localizedColumn() function.

localizedColumn Function

import { localizedColumn } from "../i18n/sd.generated";

const tag = {
  id: 1,
  name: "default",
  name_ko: "태그",
  name_en: "Tag",
};

const nestedTag = {
  id: 2,
  name: {
    ko: "태그",
    en: "Tag",
  },
};

// When Context locale is "ko"
localizedColumn(tag, "name"); // "태그"
localizedColumn(nestedTag, "name"); // "태그"

// When Context locale is "en"
localizedColumn(tag, "name"); // "Tag"
localizedColumn(nestedTag, "name"); // "Tag"

// When Context locale is "fr" (unsupported locale)
localizedColumn(tag, "name"); // "태그" (uses the default locale)

Priority Order

localizedColumn() looks for values in the following order:

Current locale	Priority
`ko`	`name_ko` → `name` → `name_en`
`en`	`name_en` → `name` → `name_ko`

When suffix columns and a locale map both exist, the suffix column for the current locale is checked first, then the locale map value. Empty strings ("") and null are skipped, and the next priority is checked.

Entity Definition

Example of an Entity with multilingual columns:

{
  "id": "Tag",
  "table": "tags",
  "props": [
    { "name": "id", "type": "integer" },
    { "name": "name", "type": "string", "length": 100, "desc": "Default name" },
    { "name": "name_ko", "type": "string", "length": 100, "nullable": true, "desc": "Korean name" },
    { "name": "name_en", "type": "string", "length": 100, "nullable": true, "desc": "English name" }
  ]
}

Using in Models

Processing in Subset

You can use localizedColumn in a Subset’s enhancer to deliver only a single name field to the client:

import { localizedColumn } from "../i18n/sd.generated";

class TagModelClass extends BaseModelClass {
  async findMany<T extends TagSubsetKey>(subset: T, params: TagListParams) {
    // ...

    const enhancers = this.createEnhancers({
      A: (row) => ({
        ...row,
        // Replace with locale-appropriate name
        displayName: localizedColumn(row, "name"),
      }),
    });

    return this.executeSubsetQuery({ subset, qb, params, enhancers });
  }
}

Using in API Response

@api({ httpMethod: "GET" })
async getTagOptions(): Promise<{ id: number; label: string }[]> {
  const tags = await this.findMany("A", { num: 100 });

  return tags.rows.map(tag => ({
    id: tag.id,
    label: localizedColumn(tag, "name") ?? tag.name,
  }));
}

Using in Frontend

The same function can be used in the frontend (exported from web’s sd.generated.ts):

import { localizedColumn } from "@/i18n/sd.generated";

function TagBadge({ tag }: { tag: Tag }) {
  return <span className="badge">{localizedColumn(tag, "name")}</span>;
}

Supported Value Shapes

localizedColumn() supports two storage shapes:

Shape	Example	Description
Suffix columns	`name`, `name_ko`, `name_en`	Store one column per locale.
Locale map	`{ name: { ko: "태그", en: "Tag" } }`	Store locale-specific values in the base column object.

The selected value can be a string or string[]. string[] values are returned as arrays and are not stringified. For suffix columns or base columns, scalar values such as number, boolean, or bigint are stringified for backward compatibility.

Suffix Column Naming Patterns

Base column	Locale columns	Description
`name`	`name_ko`, `name_en`	Name
`title`	`title_ko`, `title_en`	Title
`description`	`description_ko`, `description_en`	Description
`content`	`content_ko`, `content_en`	Content

When using suffix columns, use the {base_column}_{locale} format. When using a locale map, the base column value can store the locale-specific object.

Important Notes

localizedColumn is simply a function that selects column values. Query optimization (SELECTing only necessary columns) must be handled separately.
If all locale columns are null and the base column is also empty, undefined is returned.
If locale is not set in Context, defaultLocale is used.
If Context locale is unsupported, values are resolved from defaultLocale.

i18n Setup

Initial i18n configuration

Using the SD Function

Writing and using dictionaries

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

localizedColumn Function

Priority Order

Entity Definition

Using in Models

Processing in Subset

Using in API Response

Using in Frontend

Supported Value Shapes

Suffix Column Naming Patterns

Important Notes

i18n Setup

Using the SD Function

​localizedColumn Function

​Priority Order

​Entity Definition

​Using in Models

​Processing in Subset

​Using in API Response

​Using in Frontend

​Supported Value Shapes

​Suffix Column Naming Patterns

​Important Notes

i18n Setup

Using the SD Function

localizedColumn Function

Priority Order

Entity Definition

Using in Models

Processing in Subset

Using in API Response

Using in Frontend

Supported Value Shapes

Suffix Column Naming Patterns

Important Notes