Multi-language build

2025-01-23 17:53:04 +02:00 · 2020-12-06 22:16:52 +03:00 · 2020-12-06 22:16:52 +03:00 · 7ae2043a78
commit 7ae2043a78
parent 202eb15def
7 changed files with 178 additions and 34 deletions
--- a/build.js
+++ b/build.js
@ -2,25 +2,53 @@ const puppeteer = require('puppeteer');
 const fs = require('fs');
 const mdHtml = new (require('showdown').Converter)();

-const content = getParts({
-    path: './src/ru/clean-copy/',
-    l10n: {
-        chapter: 'Глава'
+const l10n = {
+    en: {
+        title: 'Sergey Konstantinov. The API',
+        author: 'Sergey Konstantinov',
+        chapter: 'Chapter'
    },
-    pageBreak:'<div class="page-break"></div>'
-}).join('');
+    ru: {
+        title: 'Сергей Константинов. API',
+        author: 'Сергей Константинов',
+        chapter: 'Глава'
+    }
+};

-const html = `<html><head>
-    <meta charset="utf-8"/>
-    <title>Сергей Константинов. API</title>
-    <meta name="author" content="Сергей Константинов"/>
-    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=PT+Serif&family=PT+Sans&family=Inconsolata"/>
-    <style>${fs.readFileSync('src/style.css', 'utf-8')}</style>
-</head><body>
-    <article>${content}</article>
-</body></html>`;
+buildDocs(l10n).then(() => {
+    process.exit(0);
+}, (e) => {
+    console.error(e);
+    process.exit(255);
+});

-fs.writeFileSync('./docs/API.ru.html', html);
+function buildDocs (l10n) {
+    return Promise.all(
+        Object.entries(l10n).map(([lang, l10n]) => buildDoc(lang, l10n))
+    );
+}
+
+function buildDoc (lang, l10n) {
+    const content = getParts({
+        path: `./src/${lang}/clean-copy/`,
+        l10n,
+        pageBreak:'<div class="page-break"></div>'
+    }).join('');
+
+    const html = `<html><head>
+        <meta charset="utf-8"/>
+        <title>${l10n.title}</title>
+        <meta name="author" content="${l10n.author}"/>
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=PT+Serif&family=PT+Sans&family=Inconsolata"/>
+        <style>${fs.readFileSync('src/style.css', 'utf-8')}</style>
+    </head><body>
+        <article>${content}</article>
+    </body></html>`;
+
+    fs.writeFileSync(`./docs/API.${lang}.html`, html);
+
+    return buildPdf(`./docs/API.${lang}.pdf`, html);
+}

 function getParts ({ path, l10n: { chapter }, pageBreak}) {
    const parts = [
@ -52,7 +80,7 @@ function getParts ({ path, l10n: { chapter }, pageBreak}) {
    return parts;
 }

-async function buildPdf() {
+async function buildPdf (path, html) {
    const browser = await puppeteer.launch({ headless: true });
    const page = await browser.newPage();

@ -60,17 +88,10 @@ async function buildPdf() {
        waitUntil: 'load'
    });
    const pdf = await page.pdf({
-        path: './docs/API.ru.pdf',
+        path,
        preferCSSPageSize: true,
        printBackground: true
    });
   
    await browser.close();
-}
-
-buildPdf().then(() => {
-    process.exit(0);
-}, (e) => {
-    console.error(e);
-    process.exit(255);
-})
+}
--- a/docs/API.en.html
+++ b/docs/API.en.html
@ -0,0 +1,107 @@
+<html><head>
+        <meta charset="utf-8"/>
+        <title>Sergey Konstantinov. The API</title>
+        <meta name="author" content="Sergey Konstantinov"/>
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=PT+Serif&family=PT+Sans&family=Inconsolata"/>
+        <style>body {
+    font-family: 'PT Serif';
+    font-size: 14pt;
+    text-align: justify;
+}
+
+@media screen {
+    body {
+        margin: 20px auto;
+        max-width: 60%;
+    }
+}
+
+@media print {
+    h1 {
+        margin: 4.5in 0 5.2in 0;
+    }
+    body {
+        font-size: 20pt;
+    }
+}
+
+.cc-by-nc {
+    background: transparent url(https://i.creativecommons.org/l/by-nc/4.0/88x31.png) 0 5px no-repeat;
+    padding-left: 92px;
+}
+
+code, pre {
+    font-family: Inconsolata, sans-serif;
+}
+
+code {
+    white-space: nowrap;
+}
+
+pre {
+    margin: 1em 0;
+    padding: 1em;
+    border-radius: .25em;
+    border-top: 1px solid rgba(0,0,0,.45);
+    border-left: 1px solid rgba(0,0,0,.45);
+    box-shadow: .1em .1em .1em rgba(0,0,0,.45);
+    page-break-inside: avoid;
+}
+
+pre code {
+    white-space: pre;
+}
+
+.page-break {
+    page-break-after: always;
+}
+
+a {
+    text-decoration: none;
+}
+
+h1, h2, h3, h4, h5 {
+    text-align: left;
+    font-family: 'PT Sans';
+    font-weight: bold;
+    page-break-after: avoid;
+}
+
+h1 {
+    font-size: 200%;
+}
+
+h2 {
+    font-size: 160%;
+}
+
+h3 {
+    font-size: 140%;
+}
+
+h4, h5 {
+    font-size: 120%;
+}
+
+@page {
+    size: 8.5in 11in;
+    margin: 0.5in;
+}
+
+:root {
+	--main-font: 'PT Serif';
+	--alt-font: 'PT Serif';
+	--code-font: Inconsolata;
+}</style>
+    </head><body>
+        <article><h1>Sergey Konstantinov<br/>The API</h1>
+
+<p class="cc-by-nc">This work is licensed under a <a href="http://creativecommons.org/licenses/by-nc/4.0/">Creative Commons Attribution-NonCommercial 4.0 International License</a>.</p>
+<div class="page-break"></div><h2>Introduction</h2><h3 id="chapter1onthestructureofthisbook">Chapter 1. On the Structure of This Book</h3>
+<p>The book you're holding in your hands comprises this Introduction and three large sections.</p>
+<p>In Section I we are to talk about deisgning the API as a concept: how to build the architecture properly, from a high-level planning down to final interfaces.</p>
+<p>Section II is dedicated to API's lifecycle: how interfaces evolve over time, and how to elaborate the product to match users' needs.</p>
+<p>Finally, Section III is more about un-engineering sides of the API, like supporting, marketing and working with a community.</p>
+<p>First two sections are much of of interest to engineers, when third section being more relevant to both engineers and product managers. But we insist that this section is the most important for the API software developer. Since API is the product for engineers, you cannot simply pronounce non-engineering team responsible for its product planning and support. Nobody but you understands more what product features your API is capable of.</p>
+<p>Let's start.</p><div class="page-break"></div><h2>API Design</h2></article>
+    </body></html>
--- a/docs/API.en.pdf
+++ b/docs/API.en.pdf
--- a/docs/API.ru.html
+++ b/docs/API.ru.html
@ -1,9 +1,9 @@
 <html><head>
-    <meta charset="utf-8"/>
-    <title>Сергей Константинов. API</title>
-    <meta name="author" content="Сергей Константинов"/>
-    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=PT+Serif&family=PT+Sans&family=Inconsolata"/>
-    <style>body {
+        <meta charset="utf-8"/>
+        <title>Сергей Константинов. API</title>
+        <meta name="author" content="Сергей Константинов"/>
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=PT+Serif&family=PT+Sans&family=Inconsolata"/>
+        <style>body {
    font-family: 'PT Serif';
    font-size: 14pt;
    text-align: justify;
@ -93,8 +93,8 @@ h4, h5 {
 	--alt-font: 'PT Serif';
 	--code-font: Inconsolata;
 }</style>
-</head><body>
-    <article><h1>Сергей Константинов<br/>API</h1>
+    </head><body>
+        <article><h1>Сергей Константинов<br/>API</h1>

 <p class="cc-by-nc">Это произведение доступно по <a href="http://creativecommons.org/licenses/by-nc/4.0/">лицензии Creative Commons «Attribution-NonCommercial» («Атрибуция — Некоммерческое использование») 4.0 Всемирная</a>.</p>
 <div class="page-break"></div><h2>Введение</h2><h3 id="1">Глава 1. О структуре этой книги</h3>
@ -1155,4 +1155,4 @@ GET /v1/record-views/{id}?cursor={cursor}
 <p><strong>Важно</strong>: различайте локализацию для конечного пользователя и локализацию для разработчика. В примере из п.&nbsp;12 сообщение <code>localized_message</code> адресовано пользователю — его должно показать приложение, если в коде обработка такой ошибки невозможно. Это сообщение должно быть написано на указанном в запросе языке и отформатировано согласно правилам локации пользователя. А вот сообщение <code>details.checks_failed[].message</code> написано не для пользователя, а для разработчика, который будет разбираться с проблемой. Соответственно, написано и отформатировано оно должно быть понятно для разработчика — что, скорее всего, означает «на английском языке», т.к. английский де факто является стандартом в мире разработки программного обеспечения.</p>
 <p>Следует отметить, что индикация, какие сообщения следует показать пользователю, а какие написаны для разработчика, должна, разумеется, быть явной конвенцией вашего API. В примере для этого используется префикс <code>localized_</code>.</p>
 <p>И ещё одна вещь: все строки должны быть в кодировке UTF-8 и никакой другой.</p><div class="page-break"></div></article>
-</body></html>
+    </body></html>
--- a/docs/API.ru.pdf
+++ b/docs/API.ru.pdf
--- a/src/en/clean-copy/01-Introduction/01.md
+++ b/src/en/clean-copy/01-Introduction/01.md
@ -0,0 +1,13 @@
+### On the Structure of This Book
+
+The book you're holding in your hands comprises this Introduction and three large sections.
+
+In Section I we are to talk about deisgning the API as a concept: how to build the architecture properly, from a high-level planning down to final interfaces.
+
+Section II is dedicated to API's lifecycle: how interfaces evolve over time, and how to elaborate the product to match users' needs.
+
+Finally, Section III is more about un-engineering sides of the API, like supporting, marketing and working with a community.
+
+First two sections are much of of interest to engineers, when third section being more relevant to both engineers and product managers. But we insist that this section is the most important for the API software developer. Since API is the product for engineers, you cannot simply pronounce non-engineering team responsible for its product planning and support. Nobody but you understands more what product features your API is capable of.
+
+Let's start.
--- a/src/en/clean-copy/intro.html
+++ b/src/en/clean-copy/intro.html
@ -0,0 +1,3 @@
+<h1>Sergey Konstantinov<br/>The API</h1>
+
+<p class="cc-by-nc">This work is licensed under a <a href="http://creativecommons.org/licenses/by-nc/4.0/">Creative Commons Attribution-NonCommercial 4.0 International License</a>.</p>