Markdown on KnightLiブログ

8つの代表的な設定ファイル形式はどう選ぶべきか: INI、XML、JSON、YAML、TOML から Markdown まで

Wed, 22 Apr 2026 21:48:37 +0800

コードを書く人、サーバーをいじる人、ゲーム設定を調整する人、あるいは各種ツールチェーンを保守する人にとって、設定ファイルは避けて通れません。

実際、プログラムを本当に壊すのはアルゴリズムでもフレームワークでもなく、設定の 1 行であることが少なくありません。スペースが 1 つ足りない、カンマが 1 つ多い、あるいは値の書き方がシステムの想定から外れている。代表的な設定ファイル形式を並べて考えると、自然と次の問いに戻ってきます。

人間が書きやすい形式はどれか
機械が読みやすい形式はどれか
AI Agent の時代に、設定ファイルそのものの役割は変わるのか

この記事は、その問いを簡潔に整理したものです。

01 設定ファイルとは、結局「人」と「機械」の調停である

設定ファイルをうまく言い表すなら、人間とプログラムの間で交わされる一種の「行動契約」だと言えます。

その価値は明快です。業務ロジックを書き直さなくても、再コンパイルしなくても、数行のテキストを書き換えるだけで、サイトの挙動、アプリのロジック、デプロイ方法、あるいはゲームのグラフィックや隠し設定まで変えられます。

ただし、その契約には最初から矛盾があります。

人間が欲しいのは、たとえば次のようなものです。

読みやすく、書きやすく、階層がわかりやすいこと
コメントを書けて、あとから見返しやすいこと
できるだけ重複を減らし、再利用やモジュール化がしやすいこと
小さなミスで即死しないこと

しかし機械が気にするのは、ほぼ次の 2 点です。

解析が速いこと
ルールが厳密で、型が明確で、曖昧さが少ないこと

だから設定ファイル形式は常に「人間に優しいか」「機械に優しいか」の間で引っ張られます。人間に読みやすい形式ほど、機械にとっては解析が面倒になりやすい。機械にとって処理しやすい形式ほど、人間には編集時の事故が起こりやすいのです。

02 INI: 単純でわかりやすいが、表現力は低い

まずは INI です。

長所はとてもわかりやすいです。

構造が単純
セクションとキー・バリューの組み合わせで直感的
コメントを書ける
ゲーム設定や基本的な環境変数のような軽量設定に向く

古いゲーム設定をいじったことがある人や、手動でツールのパラメータを触ったことがある人なら、一度は見たことがあるはずです。

ただし INI には明確な限界もあります。構造が平坦すぎるため、複雑なネストや配列を自然に表現しにくいのです。加えて、厳密な型システムを持たないことが多く、多くの値は結局ただの文字列として扱われ、最終的な解釈はプログラム側に委ねられます。

そのため INI は、軽作業には便利な古い道具車のようなものです。小さな用途なら快適ですが、複雑なプロジェクトになると急に力不足になります。

典型的な INI 設定はこんな形です。

[server]
host=127.0.0.1
port=8080

[feature]
enable_cache=true

03 XML: 厳密で安定しているが、とにかく書くのが重い

次は XML です。

古い Java プロジェクトを保守したことがある人や、閉じタグだらけの巨大設定ファイルを見たことがある人にはおなじみでしょう。

XML の長所は次の通りです。

階層構造が明確
コメントが書ける
ルールが厳密
schema と組み合わせると強力な検証ができる

つまり、機械は実際に読み込む前に、型、出現回数、構造制約などをかなり正確に把握できます。安全性の感覚はとても強いです。

一方で、人間にとっての負担も非常に大きいです。

タグが冗長
視覚ノイズが多い
ファイルがすぐ膨らむ
閉じタグを 1 つ落とすだけで全体が壊れやすい

XML は、印鑑が揃った正式な契約書のようなものです。機械には好かれますが、人間の保守はしんどい。最近の新規プロジェクトでは優先されにくくなりましたが、古いシステムや厳密性重視の場面ではまだ完全には消えていません。

同じ設定を XML で書くと、たとえばこうなります。

<config>
  <server>
    <host>127.0.0.1</host>
    <port>8080</port>
  </server>
  <feature>
    <enable_cache>true</enable_cache>
  </feature>
</config>

04 JSON: データ交換の王者だが、手書き設定には少し窮屈

現代開発で JSON を避けて通るのはほぼ不可能です。

JSON に対する典型的な評価はこうです。データ交換形式としては非常に強い。しかし、人間が手で保守する設定ファイルとしてはやや窮屈です。

その強みは次の通りです。

オブジェクトと配列の構造が明確
ネットワーク送信に向く
パーサーが成熟している
Web API やフロントエンド・バックエンド通信に適している

特に XML と並べると、その軽さは非常に目立ちます。同じ構造なら JSON のほうが短く、ネットワーク上でやり取りしやすいことが多いです。

ただし弱点もはっきりしています。標準 JSON はコメントを書けません。

加えて、文法も厳格です。

key は必ずダブルクォート
最後の要素に trailing comma は不可
記号を 1 つ落としただけで壊れる

そのため JSON は API やサービス間通信には最適でも、人間が説明を書きながら頻繁に編集する設定ファイルには必ずしも向きません。

たとえばこんな形です。

{
  "server": {
    "host": "127.0.0.1",
    "port": 8080
  },
  "feature": {
    "enable_cache": true
  }
}

05 YAML: 読みやすいが、インデントと暗黙型変換が怖い

Docker、CI/CD、Kubernetes、自動デプロイに触れたことがあるなら、YAML と無縁ではいられません。

最大の魅力は、見た目のきれいさです。

波括弧や引用符が少ない
インデントで階層を表せる
コメントを書ける
anchor による再利用もできる

そのため第一印象の読みやすさでは、YAML は JSON よりずっと人間向きに感じられることが多いです。

しかし問題もまさにそこにあります。複雑さを隠してしまうため、実運用では次の 2 つの事故が頻発します。

インデント地獄
暗黙の型変換

インデントの問題はわかりやすく、スペースが 1 つ多い・少ないだけで設定が壊れます。さらに厄介なのは暗黙型変換で、普通の文字列に見える値が勝手に真偽値などに解釈されることがあります。

だからこそ YAML は「見た目はいいのに、触ると痛い」形式として語られがちです。人間の可読性は高い一方で、機械の解析は意外に複雑で、パーサー実装差も起こりやすいのです。

同じ設定を YAML で書くと、たとえばこうなります。

server:
  host: 127.0.0.1
  port: 8080

feature:
  enable_cache: true

06 TOML: 可読性と確定性のバランスを取る形式

TOML はしばしば「現代的なバランス解」と見なされます。

魅力は、INI の直感性と JSON の型の明確さをある程度両立している点です。

コメントを書ける
構造がわかりやすい
型が比較的明示的
日付や時刻の表現が自然
YAML のような暗黙型変換の罠が少ない

現代のツールチェーンでも採用例が増えており、Python の pyproject.toml はその代表です。

もちろん万能ではありません。深いネストになるとやや冗長になり、パス形式の表記を何度も書くのが面倒です。ただし中小規模のプロジェクト設定、ツール設定、パッケージ管理設定なら、かなり安定した体験が得られます。

コメントを書けて、意味が明確で、機械にも無理がない形式を探すなら、TOML はかなり有力です。

典型的な TOML はこんな形です。

[server]
host = "127.0.0.1"
port = 8080

[feature]
enable_cache = true

07 `.conf` と Apache 設定: 汎用形式ではなく、ドメイン固有の文法

強調しておきたいのは、.conf を見て「統一された形式」だと思ってはいけない、ということです。

.conf は単に configuration の拡張子であって、中身の書き方はシステムごとの流儀に依存します。つまり .conf は広いカテゴリ名であって、ひとつの標準構文ではありません。

その例として Apache 設定は非常にわかりやすいです。

一部は単純な 1 行ディレクティブ
一部はスコープ付きタグ構造
Web サーバーという特定領域では非常に自然

強みは運用現場との相性の良さで、権限、ルーティング、VirtualHost などを自然に記述できます。ただし自分のエコシステム向けの性格が強く、汎用設定形式としての広がりはあまりありません。

この種の設定は、汎用フォーマットというより、特定ドメイン向けの DSL に近いものです。

たとえば最小の Apache 風設定は次のようになります。

Listen 80

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/var/www/html"
</VirtualHost>

08 Protocol Buffers: 工業級の強い型、安全性は高いが敷居も高い

Protocol Buffers は、もはや「手で設定ファイルを書く」というより、正式なデータ定義とシリアライズ方式です。

強みは非常に大きいです。

強い型
明確な schema
前方・後方互換性が高い
バイナリ転送がコンパクト
機械処理が高速

その代わり、導入コストも高いです。

まず .proto を書く必要がある
ツールとコンパイル工程が必要
小さなプロジェクトにはやや重い

そのため「小さなツールの設定をしたいだけ」という用途には向きませんが、大規模システム、RPC、分散システム、長期進化するプロトコルには非常に向いています。

書き方も「構造を定義し、そこからコードを生成する」前提です。

syntax = "proto3";

message ServerConfig {
  string host = 1;
  int32 port = 2;
  bool enable_cache = 3;
}

09 AI Agent時代には、Markdownが再び「設定方式」になるかもしれない

この話の中で最も面白いのは、Markdown まで設定形式の候補に入ってくることです。

従来のプログラマ視点では奇妙に聞こえるかもしれません。Markdown は普通、文書形式だからです。しかし対象が厳密なパーサーではなく、大規模言語モデルや AI Agent になると、この考え方は意外と筋が通っています。

なぜなら、従来のプログラムは厳密な構文と固定フィールドに依存していましたが、大規模モデルは意味、構造、文脈の理解を得意とするからです。彼らにとっては、

見出しは階層
箇条書きは手順
太字は強調
自然言語そのものがルールの器

になります。

つまり設定対象が「融通の利かないパーサー」から「意味を理解できる Agent」へ変わると、Markdown のような人間向けの構造化テキストこそ、より自然な設定手段になり得るのです。

これはとても重要な転換です。従来のソフトウェア時代では、人間が機械に合わせるために設定形式が存在していました。しかし AI の時代には、機械のほうが人間の表現へ寄ってきています。

たとえば Agent へのタスク設定は、こんなふうにそのまま書けてしまいます。

# 任务目标

为新用户写一封欢迎邮件。

## 要求

- 语气友好
- 不超过 150 字
- 提到产品的 3 个核心功能

## 禁止事项

- 不要承诺不存在的功能
- 不要使用夸张营销语气

10 では、どう選べばいいのか

ここまでの話を圧縮すると、だいたい次のように整理できます。

とにかく単純で軽く、平坦な設定がほしい: INI
強い構造、強い検証、旧システム互換がほしい: XML
ネットワーク転送や API 交換が中心: JSON
高い可読性とクラウドネイティブな運用設定がほしい: YAML
現代的で安定した汎用設定体験がほしい: TOML
特定システム内部のルールを書く: .conf / Apache 系 DSL
工業級のプロトコル設計と長期進化を重視する: Protocol Buffers
AI Agent 向けに自然な表現で指示したい: Markdown

つまり「最良の設定ファイル形式」は 1 つではありません。誰のために書くのかで変わります。

人間の保守のためか
機械の高速解析のためか
サービス間通信のためか
あるいは AI Agent の理解と実行のためか

まとめ

設定ファイルの歴史は、結局のところ、人間と機械が「理解コスト」をどちらに載せるかを何度も再配分してきた歴史です。

昔は人間が機械に合わせるしかなかったため、括弧、インデント、引用符、厳密な構文を覚える必要がありました。今は大規模言語モデルや Agent システムが成熟しつつあり、機械のほうが自然な表現を理解し始めています。その結果、「設定」という行為そのものも変わり始めています。

将来、多くの場面で設定ファイルは固定構文ではなく、構造化された意図の記述へと変わっていくかもしれません。それでも当面は、JSON、YAML、TOML、INI、XML が共存し、それぞれ最も向いた役割を担い続けるでしょう。

Hugo の Markdown で複雑なテーブルを使用する

Sun, 15 May 2022 00:00:00 +0000

Markdown 構文自体には複雑なテーブルの挿入が含まれていないため、HTML 構文を使用して実現できます。

Hugo で HTML サポートを有効にする

config.yaml
 
markup:
  goldmark:
    renderer:
      unsafe: true

unsafe:
デフォルトでは、Goldmark は生の HTML と潜在的に危険なリンクをレンダリングしません。インライン HTML や JavaScript が大量にある場合は、これをオンにする必要があります。

html構文

複雑なテーブルと単純なテーブルの間には、水平セルの結合と垂直セルの結合という 2 つの大きな違いがあります。 HTML 構文を通じてこれら 2 つの操作を実現する本質は、冗長な空白セルを削除し、特定のセルの Colspan 属性と rowspan 属性を使用して塗りつぶしを拡張することです。

水平方向のセルの結合: 1 つのセルが複数の列のスペースを占めている場合でも、colspan 属性に基づきます。垂直セルの結合: 1 つのセルが複数の行のスペースを占めている場合でも、rowspan 属性に基づきます。

行を結合する

<table>
    <tr>
        <td>列一</td>
        <td>列一</td>
   </tr>
    <tr>
        <td colspan="2">合并行</td>
    </tr>
    <tr>
        <td colspan="2">合并行</td>
    </tr>
</table>

表示効果:

列一	列一
合并行
合并行

列を結合する

<table>
    <tr>
        <td>列一</td>
        <td>列二</td>
   </tr>
    <tr>
        <td rowspan="2">合并列</td>
        <td >行二列二</td>
    </tr>
    <tr>
        <td >行三列二</td>
    </tr>
</table>

表示効果:

列一	列二
合并列	行二列二
行三列二

行と列を結合する

<table>
    <tr>
        <td>列一</td>
        <td>列二</td>
   </tr>
   <tr>
        <td colspan="2">合并行</td>
   </tr>
   <tr>
        <td>列一</td>
        <td>列二</td>
   </tr>
    <tr>
        <td rowspan="2">合并列</td>
        <td >行二列二</td>
    </tr>
    <tr>
        <td >行三列二</td>
    </tr>
</table>

表示効果:

列一	列二
合并行
列一	列二
合并列	行二列二
行三列二

無料の Google 翻訳 Web サイト、translate.google.cn を使用して Markdown ドキュメント全体を翻訳する方法

Thu, 21 Apr 2022 00:00:00 +0000

本方法已更新, 最新版请点击这里

Google 翻訳を直接使用する際の問題

一度に翻訳できる Web サイトの長さには制限があります。長い MD 文書はセクションに分けて複数回翻訳する必要があります。
Webサイトを翻訳する際には、前付のキーワードも一緒に翻訳されるため、翻訳後に前付部分を再構成する必要があります。翻訳言語が認識されないと、再編成がさらに面倒になります。
MarkDown キーワードにも上記と同様の問題が発生します。さらに、一部の言語 (ベトナム語やその他のあまり使用されていない言語など) では、MarkDown キーワードが翻訳中に翻訳結果に影響を与えることが判明しています。これは不完全な翻訳プログラムが原因である可能性があります。

翻訳プロセス

翻訳は大きく次のような工程に分かれます。

翻訳の必要のない部分を事前に抽出し、原文にマークを付けておきます。
マークされた文書を行ごとにセクションに分割し、最大長を超えないように一度にその一部のみを翻訳します。
翻訳中にネットワークエラーが発生した場合は、再試行してください
翻訳結果の元の未翻訳部分を置き換えます。
翻訳プロセスにより、一部の書式が失われ、文書の書式が再設定されます。

コードの実装

import codecs
import datetime
import glob
import json
import os
import random
import re
import ssl
import time
import urllib.parse
import urllib.request
from cgitb import text
from datetime import datetime
from importlib.resources import contents
from sre_constants import RANGE
from typing import TYPE_CHECKING
from unittest.util import strclass
from xml.etree.ElementTree import C14NWriterTarget

import execjs

ssl._create_default_https_context = ssl._create_unverified_context

class GoogleTrans(object):
    def __init__(self):
        self.url = 'https://translate.google.cn/translate_a/single'
        self.TKK = "434674.96463358"  # 随时都有可能需要更新的TKK值

        self.header = {
            "accept": "*/*",
            "accept-language": "zh-CN,zh;q=0.9",
            "cookie": "NID=188=M1p_rBfweeI_Z02d1MOSQ5abYsPfZogDrFjKwIUbmAr584bc9GBZkfDwKQ80cQCQC34zwD4ZYHFMUf4F59aDQLSc79_LcmsAihnW0Rsb1MjlzLNElWihv-8KByeDBblR2V1kjTSC8KnVMe32PNSJBQbvBKvgl4CTfzvaIEgkqss",
            "referer": "https://translate.google.cn/",
            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
            "x-client-data": "CJK2yQEIpLbJAQjEtskBCKmdygEIqKPKAQi5pcoBCLGnygEI4qjKAQjxqcoBCJetygEIza3KAQ==",
        }

        self.data = {
            "client": "webapp",  # 基于网页访问服务器
            "sl": "zh-cn",  # 源语言,auto表示由谷歌自动识别
            "tl": "en",  # 翻译的目标语言
            "hl": "zh-cn",  # 界面语言选中文，毕竟URL都是cn后缀了，就不装美国人了
            # dt表示要求服务器返回的数据类型
            "dt": ["at", "bd", "ex", "ld", "md", "qca", "rw", "rm", "ss", "t"],
            "otf": "2",
            "ssel": "0",
            "tsel": "0",
            "kc": "1",
            "tk": "",  # 谷歌服务器会核对的token
            "q": ""  # 待翻译的字符串
        }

        with open('token.js', 'r', encoding='utf-8') as f:
            self.js_fun = execjs.compile(f.read())

        # 构建完对象以后要同步更新一下TKK值
        # self.update_TKK()

    def update_TKK(self):
        url = "https://translate.google.cn/"
        req = urllib.request.Request(url=url, headers=self.header)
        page_source = urllib.request.urlopen(req).read().decode("utf-8")
        self.TKK = re.findall(r"tkk:'([0-9]+\.[0-9]+)'", page_source)[0]

    def construct_url(self):
        base = self.url + '?'
        for key in self.data:
            if isinstance(self.data[key], list):
                base = base + "dt=" + "&dt=".join(self.data[key]) + "&"
            else:
                base = base + key + '=' + self.data[key] + '&'
        base = base[:-1]
        return base

    def query(self, q, lang_from='zh-cn', lang_to=''):
        self.data['q'] = urllib.parse.quote(q)
        self.data['tk'] = self.js_fun.call('wo', q, self.TKK)
        self.data['sl'] = lang_from
        self.data['tl'] = lang_to
        url = self.construct_url()
        # print(url)
        req = urllib.request.Request(url=url, headers=self.header)
        res = urllib.request.urlopen(req).read().decode("utf-8")
        # print("res======", res)
        response = json.loads(res)

        # print(response)
        originalLanguageCode = response[2]

        targetText = ""
        originalText = ""
        for ds in response[0]:
            # print("-----------------")
            # print(ds[0])
            # print("-----------------")
            # print(ds[1])
            # print("-----------------")
            if ds[0]:
                targetText = targetText + ds[0]
            if ds[1]:
                originalText = originalText + ds[1]

        print("翻译前：{}，翻译前code：{}".format(originalText, originalLanguageCode))
        print("翻译后：{}, 翻译后code：{}".format(targetText, lang_to))

        return originalText, originalLanguageCode, targetText, lang_to

    def translate(self, sourceTxt, srcLang, targetLang, retries=0):
        print('translate retries=',  retries)
        if retries > 20:
            return
        try:
            result = self.query(sourceTxt, srcLang, lang_to=targetLang)[2]
            print(result)
            if result is None:
                retries += 1
                self.translate(sourceTxt, srcLang, targetLang, retries)
            else:
                return result
        except:
            retries += 1
            self.translate(sourceTxt, srcLang, targetLang, retries)


class MdTransItem(object):
    def __init__(self, i):
        self.delimiter = '_{:05d}_'.format(i)

# 内容无需翻译
# 比如 #date: 2022-04-01
class MdTransItemReserve(MdTransItem):
    def __init__(self, text, i):
        MdTransItem.__init__(self, i)
        self.trans_buff = self.delimiter + '\n'
        self.value = text

    def get_trans_buff(self):
        return self.trans_buff

    def compose(self, translated_md_text):
        return translated_md_text.replace(self.trans_buff, self.value)

# 内容全部需翻译
# 比如MD中的正文文本块
class MdTransItemPlainText(MdTransItem):
    def __init__(self, text, i):
        MdTransItem.__init__(self, i)
        self.trans_buff = text

    def get_trans_buff(self):
        return self.trans_buff

    def compose(self, translated_md_text):
        return translated_md_text

# 内容为#key:value形式，value需要翻译
# 比如 #title: 这是文章标题
class MdTransItemKeyValue(MdTransItem):
    def __init__(self, text, i):
        MdTransItem.__init__(self, i)
        # print(text)
        idx = text.index(':')
        # print(idx)
        lstr = text[0: idx + 1]
        rstr = text[idx + 1:].strip()
        # print(rstr)
        self.trans_buff = self.delimiter + ' \n' + \
            rstr + '  \n' + self.delimiter + ' \n'
        self.value = lstr.rstrip()

    def get_trans_buff(self):
        return self.trans_buff

    def compose(self, translated_md_text):
        # return translated_md_text.replace(self.delimiter, self.value)
        print('self.delimiter:', self.delimiter)
        print(translated_md_text)
        result_md_text = ''
        dlen = len(self.delimiter)
        idx1 = translated_md_text.index(self.delimiter)
        idx2 = translated_md_text.index(self.delimiter, idx1 + 1)

        lstr = translated_md_text[0: idx1]
        mstr = translated_md_text[idx1 + dlen + 1: idx2]
        rstr = translated_md_text[idx2 + dlen + 1:]
        rstr = rstr.lstrip()

        result_md_text = lstr + self.value + ' ' + mstr.strip() + '\n' + rstr
        return result_md_text

# 内容为### Title形式，Title需要翻译
# 比如 ### MD标题
class MdTransItemTitle(MdTransItem):
    def __init__(self, text, i):
        MdTransItem.__init__(self, i)
        idx = text.index(' ')
        lstr = text[0: idx + 1]
        rstr = text[idx + 1:]
        # print(rstr)
        self.trans_buff = self.delimiter + ' \n' + \
            rstr + '  \n' + self.delimiter + ' \n'
        self.value = lstr.rstrip()

    def get_trans_buff(self):
        return self.trans_buff

    def compose(self, translated_md_text):
        # return translated_md_text.replace(self.delimiter, self.value)
        print('self.delimiter:', self.delimiter)
        print(translated_md_text)
        result_md_text = ''
        dlen = len(self.delimiter)
        idx1 = translated_md_text.index(self.delimiter)
        idx2 = translated_md_text.index(self.delimiter, idx1 + 1)

        lstr = translated_md_text[0: idx1]
        mstr = translated_md_text[idx1 + dlen + 1: idx2]
        rstr = translated_md_text[idx2 + dlen + 1:]
        rstr = rstr.lstrip()

        result_md_text = lstr + self.value + ' ' + mstr.strip() + '\n' + rstr
        return result_md_text


# 内容为![图片标题](01.jpg) 形式，图片标题需要翻译
# 比如 ![图片名称](01.jpg)
class MdTransItemImg(MdTransItem):
    def __init__(self, text, i):
        MdTransItem.__init__(self, i)
        idx1 = text.index('[')
        idx2 = text.index(']')
        if idx1 == idx2 - 1:
            self.value = text[:-1]
            self.trans_buff = self.delimiter + '\n'
            self.type = 1
        else:
            lstr = text[0: idx1 + 1]
            mstr = text[idx1 + 1: idx2]
            rstr = text[idx2: -1]
            self.trans_buff = self.delimiter + '_B ' + mstr + ' ' + self.delimiter + '_E\n'
            self.value1 = lstr
            self.value2 = rstr
            self.type = 2

    def get_trans_buff(self):
        return self.trans_buff

    def compose(self, translated_md_text):
        if self.type == 1:
            translated_md_text = translated_md_text.replace(
                self.delimiter, self.value)
        elif self.type == 2:
            translated_md_text = translated_md_text.replace(
                self.delimiter + '_B', self.value1)
            translated_md_text = translated_md_text.replace(
                self.delimiter + '_E', self.value2)
        return translated_md_text

# 内容为#key:["values1","values2",..."valueN"]形式，value需要翻译
# 比如 keywords: ["关键词1","关键词2","关键词3"]
class MdTransItemKeyValueArray(MdTransItem):
    def __init__(self, text, i):
        MdTransItem.__init__(self, i)
        idx = text.index(':')
        # print(idx)
        lstr = text[0: idx + 1]
        self.value = lstr
        rstr = text[idx + 1:].strip()
        # print(rstr)
        # 列表内容
        if rstr.startswith('['):
            self.trans_buff = ''
            self.trans_buff = self.trans_buff + self.delimiter + '  \n'

            # print('strat with [')
            trans_str = ''
            items = rstr[2:-2].split('\",\"')
            for item in items:
                self.trans_buff = self.trans_buff + item + '\n'

            self.trans_buff = self.trans_buff + self.delimiter + '  \n'

        else:
            print("Wrong format with MdTransItemKeyValueArray:", text)

    def get_trans_buff(self):
        return self.trans_buff

    def compose(self, translated_md_text):
        print('self.delimiter:', self.delimiter)
        print(translated_md_text)
        result_md_text = ''
        dlen = len(self.delimiter)
        idx1 = translated_md_text.index(self.delimiter)
        idx2 = translated_md_text.index(self.delimiter, idx1 + 1)

        lstr = translated_md_text[0: idx1]
        mstr = translated_md_text[idx1 + dlen + 1: idx2]
        rstr = translated_md_text[idx2 + dlen + 1:]
        rstr = rstr.lstrip()

        result_md_text = lstr

        result_md_text = result_md_text + self.value + ' ['
        mstr_array = mstr.strip().split('\n')
        for m in mstr_array:
            if m.endswith('.'):
                m = m[0:-1]
            result_md_text = result_md_text + '"' + m + '",'

        if result_md_text.endswith(','):
            result_md_text = result_md_text[0: len(result_md_text) - 1]

        result_md_text = result_md_text + ']\n'
        result_md_text = result_md_text + rstr
        return result_md_text

class MdTranslater(object):
    langs = ['en', 'zh-tw', 'th', 'hi', 'ms', 'tl', 'id', 'vi']

    def cleanup(self, md_folder):
        for lang in self.langs:
            dest_filename = md_folder + '/index.' + lang + '.md'
            if os.path.exists(dest_filename):
                print('remove ', dest_filename)
                os.remove(dest_filename)

    def check_missing(self, md_folder):
        for lang in self.langs:
            dest_filename = md_folder + '/index.' + lang + '.md'
            if not os.path.exists(dest_filename):
                print('lack ', dest_filename)

    def replace_useless_char(self, tstr):
        return tstr

    def translate_md(self, src_lang, dest_lang, md_file):
        dest_filename = md_file.replace(src_lang, dest_lang)
        if os.path.exists(dest_filename):
            print('already translated ', dest_filename, ' skip.')
            return

        src_filename = md_file
        if not os.path.exists(src_filename):
            print('src file ', src_filename, ' not exist! skip.')
            return

        src_md_lines = ''
        with open(src_filename, encoding='utf-8') as src_filename_data:
            src_md_lines = src_filename_data.readlines()

        print('translate ', dest_filename, ' ...')
        is_front_matter = False
        md_trans_items = []
        for i in range(len(src_md_lines)):
            line = src_md_lines[i]
            line = self.replace_useless_char(line)
            if line.strip() == '---':
                is_front_matter = not is_front_matter
                md_trans_items.append(MdTransItemReserve(line, i))
                continue

            if is_front_matter:
                if line.startswith(('title:', 'slug:', 'description:')):
                    md_trans_items.append(MdTransItemKeyValue(line, i))
                elif line.startswith('date:'):
                    md_trans_items.append(MdTransItemReserve(line, i))
                elif line.startswith(('tags:', 'categories:', 'keywords:')):
                    md_trans_items.append(MdTransItemKeyValueArray(line, i))
                else:
                    md_trans_items.append(MdTransItemPlainText(line, i))
            else:
                if len(line.strip()) == 0:  # 空行
                    md_trans_items.append(MdTransItemPlainText(line, i))
                elif re.match('\!\[.*\]\(.*\)', line) is not None:  # 图片
                    md_trans_items.append(MdTransItemImg(line, i))
                elif line.strip().startswith('#'):  # 标题
                    md_trans_items.append(MdTransItemTitle(line, i))
                else:  # 普通文字
                    md_trans_items.append(MdTransItemPlainText(line, i))

        # 待翻译md文本
        src_md_text = ''
        for mdTransItem in md_trans_items:
            src_md_text = src_md_text + mdTransItem.get_trans_buff()

        # 分割文本，每次翻译，发送大小不大于1000
        part_src_md_text = ""
        dest_md_text = ""
        for line in src_md_text.splitlines():
            part_src_md_text = part_src_md_text + line + "\n"
            if len(part_src_md_text) > 1000:
                dest_md_text = dest_md_text + GoogleTrans().translate(part_src_md_text,
                                                                      src_lang, dest_lang) + "\n"
                part_src_md_text = ""
        if len(part_src_md_text) > 0:
            dest_md_text = dest_md_text + GoogleTrans().translate(part_src_md_text,
                                                                  src_lang, dest_lang) + "\n"

        for mdTransItem in md_trans_items:
            print(mdTransItem)
            dest_md_text = mdTransItem.compose(dest_md_text)

        final_md_text = ''
        for dline in dest_md_text.splitlines():
            final_md_text = final_md_text + dline + '  \n'

        with open(dest_filename, 'w', encoding='utf-8') as outfile:
            outfile.write(final_md_text)

    def translate_md_with_retries(self, src_lang, dest_lang, md_folder, retries=0):
        print('translate md with retries=',  retries)
        if retries > 20:
            return
        try:
            time.sleep(1)
            return self.translate_md(src_lang, dest_lang, md_folder)
        except:
            time.sleep(5)
            retries += 1
            self.translate_md_with_retries(
                src_lang, dest_lang, md_folder, retries)

    def translate_all_md(self, md_folder):
        print('translate_all_md:', md_folder)
        files = [f for f in glob.glob(
            md_folder + "/**/*.zh-cn.md", recursive=True)]
        for f in files:
            for lang in self.langs:
                self.translate_md_with_retries('zh-cn', lang, f)

参考資料

Google 翻訳では部分的に https://github.com/VictorZhang2014/free-google-translate を参照しています

Hugo 記事 (MD ファイル) のディレクトリ構成

Fri, 25 Mar 2022 00:00:00 +0000

Hugo の通常のディレクトリ構造

一般的な例は次のとおりです

content/
└── post
    ├── chinese-test
    │   ├── florian-klauer-nptLmg6jqDo-unsplash.jpg
    │   ├── helena-hertz-wWZzXlDpMog-unsplash.jpg
    │   ├── hudai-gayiran-3Od_VKcDEAA-unsplash.jpg
    │   ├── index.zh-cn.md
    │   └── luca-bravo-alS7ewQ41M8-unsplash.jpg
    ├── emoji-support
    │   ├── index.md
    │   └── the-creative-exchange-d2zvqp3fpro-unsplash.jpg
    ├── markdown-syntax
    │   ├── index.md
    │   └── pawel-czerwinski-8uZPynIu-rQ-unsplash.jpg
    ├── math-typesetting
    │   └── index.md
    ├── placeholder-text
    │   ├── index.ar.md
    │   ├── index.md
    │   └── matt-le-SJSpo9hQf7s-unsplash.jpg
    └── rich-content
        └── index.md

上に示すように、md ファイルは content/post ディレクトリに保存されます。各記事にはディレクトリがあります。記事内で使用されている画像とMDファイルは同じディレクトリに配置されています。記事数が少ない場合にはこの構造でも大きな問題はありませんが、ブログを書く時間が長くなり記事数が増えてくると、投稿ディレクトリ内のディレクトリが多くなり、探すのが面倒になってきます。次のディレクトリ構造が使用できます

時間ごとに分割されたディレクトリ構造

content/
└── post
    ├── 2020
    │   ├── 1.zh-cn.md
    │   ├── 1.zh-tw.md
    │   └── 2
    │       ├── 1.jpg
    │       ├── 2.jpg
    │       ├── 3.png
    │       ├── index.zh-cn.md
    │       ├── index.zh-tw.md
    │       └── 4.png
    ├── 2021
    │   ├── 1.zh-cn.md
    │   ├── 1.zh-tw.md
    │   ├── 2.zh-cn.md
    │   ├── 2.zh-tw.md
    │   ├── 3.zh-cn.md
    │   ├── 3.zh-tw.md
    │   ├── 4.zh-cn.md
    │   ├── 4.zh-tw.md
    │   ├── 5.zh-cn.md
    │   └── 5.zh-tw.md
    └── 2022
        ├── 1.zh-cn.md
        ├── 1.zh-tw.md
        └── 2
            ├── 1.png
            ├── 2.png
            ├── 3.png
            ├── 4.png
            ├── 5.png
            ├── 6.png
            ├── 7.png
            ├── 8.png
            ├── 9.png
            ├── index.zh-cn.md
            └── index.zh-tw.md

上に示すように

post ディレクトリの下に、まず年に基づいてサブディレクトリを作成します。もちろん、更新頻度が高い場合は、年/月または年/月/日に基づいて第 1 レベルのディレクトリを作成することもできます。
画像のない記事は年月日ディレクトリに直接保存されます。
画像がある場合は、追加の第 1 レベルのディレクトリを作成します。 md ファイルの名前は、index.lang.md です (他の名前のファイルを使用すると、画像は表示されません)。画像は同じディレクトリに配置されます。
さまざまな言語の MD ファイルがまとめられ、index.zh-cn.md、index.zh-tw.md などのさまざまなindex.lang.md によって区別されます。

Markdown on KnightLiブログ

8つの代表的な設定ファイル形式はどう選ぶべきか: INI、XML、JSON、YAML、TOML から Markdown まで

01 設定ファイルとは、結局「人」と「機械」の調停である

02 INI: 単純でわかりやすいが、表現力は低い

03 XML: 厳密で安定しているが、とにかく書くのが重い

04 JSON: データ交換の王者だが、手書き設定には少し窮屈

05 YAML: 読みやすいが、インデントと暗黙型変換が怖い

06 TOML: 可読性と確定性のバランスを取る形式

07 .conf と Apache 設定: 汎用形式ではなく、ドメイン固有の文法

08 Protocol Buffers: 工業級の強い型、安全性は高いが敷居も高い

09 AI Agent時代には、Markdownが再び「設定方式」になるかもしれない

10 では、どう選べばいいのか

まとめ

Hugo の Markdown で複雑なテーブルを使用する

Hugo で HTML サポートを有効にする

html構文

行を結合する

列を結合する

行と列を結合する

無料の Google 翻訳 Web サイト、translate.google.cn を使用して Markdown ドキュメント全体を翻訳する方法

Google 翻訳を直接使用する際の問題

翻訳プロセス

コードの実装

参考資料

Hugo 記事 (MD ファイル) のディレクトリ構成

Hugo の通常のディレクトリ構造

時間ごとに分割されたディレクトリ構造

07 `.conf` と Apache 設定: 汎用形式ではなく、ドメイン固有の文法