Multilingual Content

Essepage lets you write content in multiple languages in a single file without creating a separate page file for each language.

The basic workflow is as follows:

Configure the languages you want to use in +essepage.config.json.
Write the default content and its translations in a single page file.
Check the translated result at each language URL.
Add a language switcher.

Live Preview is also available for multilingual content.

Full Code

Before you begin, take a quick look at the completed result and the full code.

Configuring Multiple Languages

To use multilingual content, configure the additional languages in the +essepage.config.json file at the project root.

The file structure looks like this:

/
├── +essepage.config.json
└── public
    └── +page.essepage

To use Korean and Japanese as additional languages, write:

{
    "additional_languages": "ko, ja"
}

Enter comma-separated language codes in additional_languages.

After saving this setting, you can use language-specific URLs such as:

/about
/ko/about
/ja/about

You can add as many languages as you need.

Setting the Default Language (Optional)

Use default_language to specify the default language of your website.

The default_language setting is not required to use language-specific URLs. However, when you set the default language, the lang attribute of the generated <html> element is automatically set for URLs without a language code.

If the default language is English, write:

{
    "default_language": "en",
    "additional_languages": "ko, ja"
}

The document language is then set for each language URL as follows:

/about     → <html lang="en">
/ko/about  → <html lang="ko">
/ja/about  → <html lang="ja">

If Korean is the default language, you can configure it as follows:

{
    "default_language": "ko",
    "additional_languages": "en, ja"
}

Writing Multilingual Content

Suppose your multilingual configuration is:

{
    "default_language": "en",
    "additional_languages": "ko, ja"
}

The basic multilingual content syntax is:

{{# Default language [@ko] Korean [@ja] Japanese #}}

Multilingual content begins with {{# and ends with #}}.

Each part has the following role:

Syntax	Meaning
`{{#`	Begins multilingual content
`Text`	Default-language content
`[@ko]`	Begins Korean content
`Text`	Korean content
`[@ja]`	Begins Japanese content
`Text`	Japanese content
`#}}`	Ends multilingual content

On a website where English is the default language, write a title in English, Korean, and Japanese as follows:

<h1>
    {{# Welcome [@ko] 환영합니다 [@ja] ようこそ #}}
</h1>

The displayed content depends on the page language.

Page language	Displayed content
Default language	Welcome
Korean	환영합니다
Japanese	ようこそ

Multilingual HTML Content

You can use multilingual syntax inside regular HTML elements.

<h1>
    {{# Build Better Websites [@ko] 더 나은 웹사이트를 만드세요 [@ja] より良いWebサイトを作りましょう #}}
</h1>

<p>
    {{# Create and publish your website directly in the browser. [@ko] 브라우저에서 직접 웹사이트를 만들고 공개하세요. [@ja] ブラウザでWebサイトを作成し、そのまま公開できます。 #}}
</p>

<a href="/get-started">
    {{# Get Started [@ko] 시작하기 [@ja] はじめる #}}
</a>

When the page language changes, the heading, description, and link text change together.

You can also provide an entire section containing multiple HTML elements for each language.

{{#
<section>
    <h1>About Our Service</h1>
    <p>We help people build and publish websites.</p>
</section>

[@ko]
<section>
    <h1>서비스 소개</h1>
    <p>누구나 웹사이트를 만들고 공개할 수 있도록 도와드립니다.</p>
</section>

[@ja]
<section>
    <h1>サービスについて</h1>
    <p>誰でもWebサイトを作成して公開できるようサポートします。</p>
</section>
#}}

If the HTML structure is the same in every language, applying multilingual syntax to each sentence is easier to manage.

If the content organization or HTML structure needs to differ by language, you can provide the entire section separately for each language.

Writing Multilingual Markdown

You can also use multilingual syntax in Markdown content.

# {{# About Us [@ko] 소개 [@ja] 私たちについて #}}

{{#
We create tools that help people build and publish websites.

[@ko]
누구나 웹사이트를 만들고 공개할 수 있도록 돕는 도구를 만듭니다.

[@ja]
誰でもWebサイトを作成して公開できるツールを開発しています。
#}}

## {{# Main Features [@ko] 주요 기능 [@ja] 主な機能 #}}

- {{# Browser-based editor [@ko] 브라우저 기반 에디터 [@ja] ブラウザベースのエディター #}}
- {{# Live preview [@ko] 실시간 미리보기 [@ja] ライブプレビュー #}}
- {{# Simple publishing [@ko] 간편한 공개 [@ja] 簡単な公開 #}}

You can use multilingual syntax in Markdown headings, paragraphs, and lists.

Alternatively, you can write the entire content separately for each language.

{{#

# About Us

We create tools that help people build and publish websites.

## Main Features

- Browser-based editor
- Live preview
- Simple publishing

[@ko]

# 소개

누구나 웹사이트를 만들고 공개할 수 있도록 돕는 도구를 만듭니다.

## 주요 기능

- 브라우저 기반 에디터
- 실시간 미리보기
- 간편한 공개

[@ja]

# 私たちについて

誰でもWebサイトを作成して公開できるツールを開発しています。

## 主な機能

- ブラウザベースのエディター
- ライブプレビュー
- 簡単な公開

#}}

You can use the same method to write content in multiple languages in an Article File such as @title.md.

See Markdown to learn more about using Markdown.

Language-Specific URLs

Suppose you have the following page file:

/public/about/+page.essepage

and the following configuration in +essepage.config.json:

{
    "default_language": "en",
    "additional_languages": "ko, ja"
}

You can access the page through the following URLs:

Language	URL
Default language	`.../about`
Korean	`.../ko/about`
Japanese	`.../ja/about`

Each URL uses the same page file but displays content matching the language in the URL.

<h1>
    {{# About Us [@ko] 소개 [@ja] 私たちについて #}}
</h1>

Each URL displays the following content:

/about → About Us
/ko/about → 소개
/ja/about → 私たちについて

You do not need to create a separate page for each language, so you can manage all translations in a single file.

Automatic Language Handling for Internal Links

When you enter a regular URL for an internal link, Essepage automatically preserves the language of the current page.

To link to the About page, write:

<a href="/about">
    {{# About [@ko] 소개 [@ja] 私たちについて #}}
</a>

Do not add the language code directly to href.

<a href="/about">...</a>

The link automatically points to a URL matching the language of the current page.

Current page language	Destination URL
Default language	`/about`
Korean	`/ko/about`
Japanese	`/ja/about`

Because Essepage automatically adds the current language to the URL, you do not need to make href multilingual.

<!-- ❌ You do not need to write it this way. -->
<a href="{{# /about [@ko] /ko/about [@ja] /ja/about #}}">...</a>

By using multilingual syntax in a layout or component, you can manage the navigation shared by every page in one place.

<nav>
    <a href="/">
        {{# Home [@ko] 홈 [@ja] ホーム #}}
    </a>

    <a href="/about">
        {{# About [@ko] 소개 [@ja] 私たちについて #}}
    </a>

    <a href="/contact">
        {{# Contact [@ko] 문의 [@ja] お問い合わせ #}}
    </a>
</nav>

The current page language is automatically applied to each link.

See Layouts and Components for more information.

Creating a Language Switcher

You can provide a language switcher that lets visitors select their preferred language.

To change the language and move to that language’s homepage, write:

<nav>
    <a href="/" hreflang="en">English</a>
    <a href="/ko" hreflang="ko">한국어</a>
    <a href="/ja" hreflang="ja">日本語</a>
</nav>

This method takes visitors to the homepage of the selected language.

However, it is usually more natural to keep visitors on the current page and change only the language. For this, use Essepage’s language-path syntax.

<nav>
    <a href="./[@]" hreflang="en">English</a>
    <a href="./[@ko]" hreflang="ko">한국어</a>
    <a href="./[@ja]" hreflang="ja">日本語</a>
</nav>

Each link has the following meaning:

Link	Destination
`./[@]`	The current page in the default language
`./[@ko]`	The current page in Korean
`./[@ja]`	The current page in Japanese

For example, when switching languages from /ko/about or /ja/about, the /about page path is preserved and only the language changes.

When Multilingual Content Does Not Appear

If the correct content or URL does not appear for a language, check the following.

When a Language-Specific URL Does Not Open

The +essepage.config.json file is located at the project root
additional_languages is configured
The language codes are separated by commas
The quotation marks and commas in the JSON are correct
The URL you are checking includes a configured language code

When Translated Content Does Not Appear

The multilingual content begins with {{# and ends with #}}
Language markers such as [@ko] and [@ja] are entered correctly
The default-language content appears before the first language marker
The language is included in +essepage.config.json

When Internal Links Do Not Preserve the Language

Check that internal links use regular URLs, as shown below:

<a href="/about">About</a>

Check that the language switcher uses the syntax for changing the language of the current page.

<a href="./[@]">English</a>
<a href="./[@ko]">한국어</a>
<a href="./[@ja]">日本語</a>

If you have just applied changes to the published site, wait for the cache to update and then refresh the page.

Next Steps

Now that you understand how to create multilingual content, continue with the following documents:

Translate page titles and search-result descriptions: Metadata and SEO
Apply styles to multilingual content: CSS
Write multilingual documents in Markdown: Markdown
Use shared multilingual navigation across pages: Layouts
Manage reusable multilingual elements in separate files: Components
Use image URLs on multilingual pages: External Files

Languages

On this page

Title