EmDash는 Astro의 내장 i18n 라우팅과 통합되어 다국어 콘텐츠 관리를 제공합니다. Astro는 URL 라우팅과 로케일 감지를 처리하고, EmDash는 번역된 콘텐츠 저장 및 검색을 처리합니다.
각 번역은 고유한 슬러그, 상태 및 리비전 기록을 가진 완전하고 독립적인 콘텐츠 항목입니다. 게시물의 프랑스어 버전은 초안 상태일 수 있고 영어 버전은 게시될 수 있습니다.
구성
Astro 구성에 i18n 블록을 추가하여 i18n을 활성화합니다. EmDash는 로케일 목록, 기본 로케일 및 폴백 체인에 대해 동일한 구성을 읽습니다.
import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";
export default defineConfig({
i18n: {
defaultLocale: "en",
locales: ["en", "fr", "es"],
fallback: { fr: "en", es: "en" },
},
integrations: [
emdash({
database: sqlite({ url: "file:./data.db" }),
storage: local({
directory: "./uploads",
baseUrl: "/_emdash/api/media/file",
}),
}),
],
});Astro 구성에 i18n이 없으면 모든 i18n 기능이 비활성화되고 EmDash는 단일 언어 CMS로 작동합니다.
번역 작동 방식
EmDash는 로케일당 행 모델을 사용합니다. 각 번역은 고유한 ID, 슬러그 및 상태를 가진 데이터베이스의 자체 행이며, 공유 translation_group 식별자를 통해 다른 번역과 연결됩니다. 세 개의 번역이 있는 posts 테이블은 다음과 같습니다:
ec_posts:
id | slug | locale | translation_group | status
---------|-------------|--------|-------------------|----------
01ABC... | my-post | en | 01ABC... | published
01DEF... | mon-article | fr | 01ABC... | draft
01GHI... | mi-entrada | es | 01ABC... | published이 설계는 다음을 의미합니다:
- 로케일별 슬러그 —
/blog/my-post와/fr/blog/mon-article이 자연스럽게 작동합니다 - 로케일별 게시 — 프랑스어를 초안으로 유지하면서 영어 버전을 게시합니다
- 로케일별 리비전 — 각 번역에는 고유한 리비전 기록이 있습니다
- 단일 로케일 쿼리 — 목록 쿼리는 하나의 로케일에 대한 항목만 반환합니다
번역된 콘텐츠 쿼리
단일 항목
특정 번역을 검색하려면 getEmDashEntry에 locale을 전달합니다. 생략하면 요청의 현재 로케일(Astro의 i18n 미들웨어에 의해 설정됨)이 기본값입니다.
---
import { getEmDashEntry } from "emdash";
const { slug } = Astro.params;
const { entry: post, error } = await getEmDashEntry("posts", slug, {
locale: Astro.currentLocale,
});
if (!post) return Astro.redirect("/404");
---
<article>
<h1>{post.data.title}</h1>
</article>폴백 체인
요청된 로케일에 대한 콘텐츠가 없으면 EmDash는 Astro 구성에 정의된 폴백 체인을 따릅니다. fallback: { fr: "en" }의 경우:
- 요청된 로케일(
fr) 시도 - 폴백 로케일(
en) 시도 - 기본 로케일 시도
폴백은 단일 항목 쿼리에만 적용됩니다. 목록 쿼리는 요청된 로케일에 대한 항목만 반환합니다.
메뉴
메뉴는 로케일별입니다 — 동일한 name(예: "primary")이 여러 로케일에 존재할 수 있으며 모두 공유 translation_group을 통해 연결됩니다. 메뉴 항목은 참조된 콘텐츠의 활성 로케일 버전에 대해 콘텐츠 참조를 해결합니다.
다음 컴포넌트는 활성 로케일에 대한 기본 메뉴를 가져옵니다:
---
import { getMenu } from "emdash";
const menu = await getMenu("primary", { locale: Astro.currentLocale });
---
<nav aria-label="Primary">
<ul>
{menu?.items.map((item) => (
<li><a href={item.url}>{item.label}</a></li>
))}
</ul>
</nav>관리자의 메뉴 목록에서 기존 메뉴의 번역을 생성합니다 — 항목은 reference_id를 그대로 유지하며 복제되고(참조된 콘텐츠의 translation_group을 저장함), 새 메뉴의 링크는 자동으로 올바른 로케일별 콘텐츠를 가리킵니다.
분류법(카테고리, 태그)
용어는 로케일별입니다. 정의(_emdash_taxonomy_defs)도 로케일별이므로 label / labelSingular도 번역할 수 있습니다. 피벗 content_taxonomies.taxonomy_id는 용어의 translation_group을 저장하므로 단일 할당이 콘텐츠의 모든 로케일을 포괄합니다.
다음 예제는 활성 로케일에 대한 카테고리와 게시물의 용어를 가져옵니다:
---
import { getTaxonomyTerms, getEntryTerms } from "emdash";
const categories = await getTaxonomyTerms("category", {
locale: Astro.currentLocale,
});
const terms = await getEntryTerms("posts", post.id, undefined, {
locale: Astro.currentLocale,
});
---콘텐츠를 번역하면 소스의 용어 할당이 자동으로 상속됩니다 — 용어 자체만 한 번 번역하면 되며, 용어를 사용하는 모든 게시물은 읽기 시 올바른 로케일로 확인됩니다.
컬렉션 목록
로케일별로 컬렉션을 필터링합니다:
---
import { getEmDashCollection } from "emdash";
const { entries: posts } = await getEmDashCollection("posts", {
locale: Astro.currentLocale,
status: "published",
});
---
<ul>
{posts.map((post) => (
<li><a href={`/${post.data.slug}`}>{post.data.title}</a></li>
))}
</ul>언어 전환기
getTranslations를 사용하여 현재 항목의 기존 번역에 연결하는 언어 전환기를 구축합니다:
---
import { getTranslations } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";
interface Props {
collection: string;
entryId: string;
}
const { collection, entryId } = Astro.props;
const { translations } = await getTranslations(collection, entryId);
---
<nav aria-label="Language">
<ul>
{translations.map((t) => (
<li>
<a
href={getRelativeLocaleUrl(t.locale, `/blog/${t.slug}`)}
aria-current={t.locale === Astro.currentLocale ? "page" : undefined}
>
{t.locale.toUpperCase()}
</a>
</li>
))}
</ul>
</nav>getTranslations 함수는 동일한 번역 그룹 내의 모든 로케일 변형을 반환합니다:
const { translationGroup, translations } = await getTranslations("posts", post.entry.id);
// translations: [
// { locale: "en", id: "01ABC...", slug: "my-post", status: "published" },
// { locale: "fr", id: "01DEF...", slug: "mon-article", status: "draft" },
// ]관리자에서 번역 관리
콘텐츠 목록
i18n이 활성화되면 콘텐츠 목록에 다음이 표시됩니다:
- 각 항목의 로케일을 표시하는 로케일 열
- 로케일 간 전환을 위한 도구 모음의 로케일 필터
번역 생성
편집기에서 콘텐츠 항목을 엽니다. 사이드바에는 구성된 모든 로케일을 나열하는 번역 패널이 표시됩니다. 각 로케일에 대해:
- “번역” — 번역이 없는 로케일에 표시됩니다 — 클릭하여 생성합니다
- “편집” — 기존 번역이 있는 로케일에 표시됩니다 — 클릭하여 이동합니다
- 현재 로케일은 체크 표시로 표시됩니다
번역을 생성할 때 새 항목은 소스 로케일의 데이터로 미리 채워지고 {소스-슬러그}-{로케일}의 기본 슬러그가 할당됩니다. 필요에 따라 슬러그와 콘텐츠를 조정한 다음 저장합니다.
로케일별 게시
각 번역에는 고유한 상태가 있습니다. 번역을 독립적으로 게시, 게시 취소 또는 예약합니다. 프랑스어 버전은 초안일 수 있고 영어 버전은 라이브일 수 있습니다.
콘텐츠 API
locale 매개변수
모든 콘텐츠 API 경로는 선택적 locale 쿼리 매개변수를 허용합니다:
GET /_emdash/api/content/posts?locale=fr
GET /_emdash/api/content/posts/my-post?locale=fr생략하면 구성된 기본 로케일이 기본값입니다.
API를 통한 번역 생성
콘텐츠 생성 엔드포인트에 locale과 translationOf를 전달하여 번역을 생성합니다:
POST /_emdash/api/content/posts
Content-Type: application/json
{
"locale": "fr",
"translationOf": "01ABC...",
"data": {
"title": "Mon Article",
"slug": "mon-article"
}
}새 항목은 소스 항목의 translation_group을 공유하고 초안으로 시작합니다.
번역 나열
주어진 항목에 대한 모든 번역을 검색합니다:
GET /_emdash/api/content/posts/01ABC.../translations번역 그룹 ID와 ID, 슬러그 및 상태가 있는 로케일 변형 배열을 반환합니다.
CLI
CLI는 콘텐츠 명령에서 --locale 플래그를 지원합니다:
# 프랑스어 게시물 나열
emdash content list posts --locale fr
# 프랑스어로 특정 항목 가져오기
emdash content get posts my-post --locale fr
# 기존 항목의 프랑스어 번역 생성
emdash content create posts --locale fr --translation-of 01ABC...다국어 콘텐츠 시딩
시드 파일은 locale과 translationOf를 사용하여 번역을 표현합니다:
{
"content": {
"posts": [
{
"id": "welcome",
"slug": "welcome",
"locale": "en",
"status": "published",
"data": { "title": "Welcome" }
},
{
"id": "welcome-fr",
"slug": "bienvenue",
"locale": "fr",
"translationOf": "welcome",
"status": "draft",
"data": { "title": "Bienvenue" }
}
]
}
}translationOf 참조가 올바르게 해결되도록 소스 로케일 항목은 시드 파일에서 번역보다 먼저 나타나야 합니다.
필드 번역 가능성
각 필드에는 translatable 설정이 있습니다(기본값: true). 번역을 생성할 때:
- 번역 가능한 필드는 편집을 위해 소스 로케일에서 미리 채워집니다
- 번역 불가능한 필드는 복사되고 그룹의 모든 번역에서 동기화됩니다
status, published_at, author_id와 같은 시스템 필드는 항상 로케일별이며 동기화되지 않습니다.
URL 전략
EmDash는 로케일 URL을 관리하지 않습니다 — Astro가 라우팅을 처리합니다. 일반적인 패턴:
# prefix-other-locales(Astro 기본값)
/blog/my-post → en(기본 로케일, 접두사 없음)
/fr/blog/mon-article → fr
# prefix-always
/en/blog/my-post → en
/fr/blog/mon-article → fr라우팅 모드에 관계없이 올바른 URL을 구축하려면 astro:i18n의 getRelativeLocaleUrl을 사용합니다.
다국어 콘텐츠 가져오기
관리 마이그레이션 도구를 통해 WordPress 콘텐츠를 가져옵니다 — 콘텐츠 가져오기 및 WordPress에서 마이그레이션을 참조하세요. WXR 내보내기에는 WPML 또는 Polylang이 추가하는 로케일 및 번역 그룹 구조가 포함되지 않으므로 가져온 콘텐츠는 기본 로케일에 도달합니다.
가져온 콘텐츠에서 번역을 구축하려면 번역된 항목을 생성하고 원본에 연결합니다:
emdash content create posts --locale fr --translation-of 01ABC...이는 위의 다국어 콘텐츠 시딩에 표시된 --locale / --translation-of 워크플로와 동일하며 가져오기가 완료된 후 적용됩니다.
다음 단계
- 콘텐츠 쿼리 — 전체 쿼리 API 참조
- 콘텐츠 작업 — 관리 콘텐츠 관리
- Astro i18n 라우팅 — Astro 라우팅 구성