Skip to content

README_ja.md

Latest commit

 

History

History
352 lines (247 loc) · 10.9 KB

README_ja.md

File metadata and controls

352 lines (247 loc) · 10.9 KB
Raw

YAMultilingualMarkdown

YAMultilingualMarkdownは、Yet Another Multilingual MarkdownをHTMLなど他の形式に変換するユーティリティです。

Yet Another Multilingual Markdown（記述形式）は、複数の言語を記述するために作られたMarkdownの方言です。YAMultilingualMarkdown（ツール）は、Yet Another Multilingual Markdown文書から指定された言語の内容だけを取り出しつつ、他の形式に変換します。

使い方

概要

ya_multilingual_markdown [OPTIONS] [FILE]

オプション

ya_multilingual_markdown --helpと入力すると、コマンドラインオプションの一覧が出力されます。

Convert Yet Another Multilingual Markdown to HTML and other formats

Usage:
  ya_multilingual_markdown [OPTIONS] [FILE]

Options:
        --output-format=FORMAT       Output format
                                     (html|kramdown|markdown)
                                     (default: html)
        --langs=LANG1,LANG2,...      Languages to be included
                                     (omitting this option implies all)
        --heading-lang-sep=STRING    Languages separator in headings
                                     (default: " / ")
        --lang-attr-name=STRING      Attribute name for language
                                     (default: lang)
        --html-output-type=TYPE      Output type for HTML output
                                     (fragment|document)
                                     (default: fragment)
        --html-template-file=FILE    HTML document template file in eRuby format
        --html-link-suffixes=FROM:TO,...
                                     Link suffixes to rewrite in HTML output
                                     (default: .md:.html)
        --show-default-html-template Show default HTML document template
        --log-level=SEVERITY         Log level
                                     (unknown|fatal|error|warn|info|debug)
                                     (default: warn)
        --help                       Show help message
        --version                    Show version

使用例

多言語コンテンツ：見出し・段落・その他の要素

単純なYet Aonther Multilingual Markdown文書は次のようなものです（ファイル名は仮にsnow_white.mdとします）：

# Schneeweißchen
{: lang="de"}

# Little Snow-white
{: lang="en"}

Es war einmal mitten im Winter,...
{: lang="de"}

Once upon a time in the middle of winter,...
{: lang="en"}

（kramdownふうの（PHP Markdown Extraふうの）拡張構文（{: name="value"}）を使って、ブロック要素に属性を設定できます。）

すべての言語を出力する

言語関係のオプションを指定せずに実行すると、すべての言語が出力されます。

ya_multilingual_markdown snow_white.md

出力の抜粋：

<h1><span lang="de">Schneeweißchen</span> / <span lang="en">Little Snow-white</span></h1>

<p lang="de">Es war einmal mitten im Winter,...</p>

<p lang="en">Once upon a time in the middle of winter,...</p>

ウェブブラウザ上で想定される表示：

Schneeweißchen / Little Snow-white

Es war einmal mitten im Winter, ...

Once upon a time in the middle of winter, ...

一つの言語だけを取り出す

--langs=enとオプションを指定すると、enという値のlang属性を持った要素（およびlang属性を持たない要素）だけが出力されます。

ya_multilingual_markdown --langs=en snow_white.md

出力の抜粋：

<h1><span lang="en">Little Snow-white</span></h1>


<p lang="en">Once upon a time in the middle of winter, ...</p>

ウェブブラウザ上で想定される表示：

Little Snow-white

Once upon a time in the middle of winter, ...

複数の言語を取り出す

--langs=de,enとオプションを指定すると、deまたはenという値のlang属性を持った要素（およびlang属性を持たない要素）が出力されます。

ya_multilingual_markdown --langs=de,en snow_white.md

出力の抜粋：

<h1><span lang="de">Schneeweißchen</span> / <span lang="en">Little Snow-white</span></h1>

<p lang="de">Es war einmal mitten im Winter,...</p>

<p lang="en">Once upon a time in the middle of winter,...</p>

ウェブブラウザ上で想定される表示：

Schneeweißchen / Little Snow-white

Es war einmal mitten im Winter, ...

Once upon a time in the middle of winter, ...

YAMLフロントマター内のメタデータ

文書のメタデータを、JekyllふうのYAMLフロントマターに記述できます。

YAMLフロントマター付きの単純なYet Aonther Multilingual Markdown文書は次のようなものです（snow_white_with_metadata.md）：

---
title: Little Snow-white
author:
  - Jacob Ludwig Karl Grimm
  - Wilhelm Carl Grimm
meta:
  - name: original title
    content: Schneeweißchen
    lang: de
  - name: translator
    content: Margaret Hunt
    lang: en
---
...

（authorというキーは<meta name="author" .../>の省略形です。）

すべての言語を出力に含めてみましょう。

ya_multilingual_markdown snow_white_with_metadata.md

出力の抜粋：

<title>Little Snow-white</title>
<meta name="author" content="Jacob Ludwig Karl Grimm" />
<meta name="author" content="Wilhelm Carl Grimm" />
<meta name="original title" content="Schneeweißchen" lang="de" />
<meta name="translator" content="Margaret Hunt" lang="en" />
<p>...</p>

メタデータも言語に基づいてフィルタをかけることができます。

enだけを出力させてみましょう（結果的にdeを除外することになります）。

ya_multilingual_markdown --langs=en snow_white_with_metadata.md

出力の抜粋：

<title>Little Snow-white</title>
<meta name="author" content="Jacob Ludwig Karl Grimm" />
<meta name="author" content="Wilhelm Carl Grimm" />
<meta name="translator" content="Margaret Hunt" lang="en" />
<p>...</p>

完全なHTML文書を出力させる

--html-output-type=documentを指定すると、HTMLの断片ではなく完全なHTML文書が出力されます。

入力：

---
title: Little Snow-white
---
Once upon a time in the middle of winter, ...

コマンドライン：

ya_multilingual_markdown --html-output-type=document snow_white_with_title.md

出力：

<!DOCTYPE html>
<html>
  <head>
    <title>Little Snow-white</title>
  </head>
  <body>
    <p>Once upon a time in the middle of winter, ...</p>
  </body>
</html>

--html-template-file=FILEで指定するとカスタムテンプレートを使えます。テンプレートはeRuby形式で記述してください。ツールに内蔵されたデフォルトのテンプレートを表示させるには、--show-default-html-templateを使ってください。

インストール方法

gem install ya_multilingual_markdown

あるいは

git clone https://github.com/hisashim/ya_multilingual_markdown
cd ya_multilingual_markdown
rake install

必要なもの

実行時に必要なもの：

開発時に必要なもの（上記に加えて）：

注意点

制限事項と既知の問題

  • YAMultilingualMarkdownは、kramdownを土台にして作られてはいるものの、kramdownの拡張構文のうち、ごく一部分しかサポートしていません。

  • 複数の言語を含む見出しについては、ALD（Attribute List Definition：属性リスト定義）を記述できるのは、各見出しの_後_だけです。

    サポートされている記述方法：

    # Schneeweißchen
{: lang="de"}

# Little Snow-white
{: lang="en"}

    サポート外：

    {: lang="de"}
# Schneeweißchen

{: lang="en"}
# Little Snow-white

    この制約により、比較的単純な仕組みで、一連の見出しの冒頭にも末尾にもidを記述できるようになっています。

    {: #title}
# Schneeweißchen
{: lang="de"}

# Little Snow-white
{: lang="en"}

    # Schneeweißchen
{: lang="de"}

# Little Snow-white
{: lang="en"}
{: #title}

開発の動機

Yet Aonther Multilingual Markdownとその処理ツールは、翻訳書に適した原稿形式を求めて生まれました。

原文と訳文の両方が載った対訳形式のゲラ刷りがあると、訳者が作品を見直すときに役立ちます。原稿自体が一種の対訳形式になっていることも、原稿内を検索して編集するときに便利です。

ローカライゼーション／多言語化プロジェクトへの一般的で効果的なアプローチとして、翻訳されたテキストを原文とは別のファイルに収めるやり方がありますが、小規模なプロジェクトでは、複数の言語を単一のファイルに収められる形式も便利です。Yet Aonther Multilingual Markdownは、そのような形式と処理ツールの概念実証を開発する試みです。

参考資料

ライセンス

このソフトウェアはMIT licenseに基づきライセンスされています。

謝辞

次の方々に深く感謝します：

  • Koichi Sasada：同氏が開発された原稿プリプロセッサから、多言語を扱える軽量なマークアップ形式のヒントを得ました。
  • kramdownの開発陣

Contributors