Add babelquarto post part 1

_freeze/posts/2024-12-06_babelquarto/index/execute-results/html.json

@@ -0,0 +1,15 @@
+{
+  "hash": "4ef481d7cffddc3c3e4a5ce8b93ebd61",
+  "result": {
+    "engine": "knitr",
+    "markdown": "---\ntitle: \"Multilingual webpages with babelquarto\"\ndescription:\n  Do you speak my language?\ndate: 2024-12-06\ndate-modified: today\nimage: https://i.giphy.com/W69vZGazsH2LDnKCzY.webp\ncitation:\n  url: 2024-12-06_babelquarto\nlang: en\ncategories:\n  - R\n  - blogging\n  - Quarto\n---\n\n\n\n## Say hi to `babelquarto`\n\n\n\n\n\n\n\n[Quarto](https://quarto.org) is an amazingly flexible tool connecting the data analysis powers of languages like R, python, and Julia to output formats ranging from PDF to websites. New features are rapidly released, but one that has been lacking so far is support for multilingual websites[^1]. Fortunately, developers (namely `@maelle`) at [rOpenSci](https://ropensci.org/) have stepped up to fill the gap with the `babelquarto` R package. Here, I demonstrate how to use it and point out some pitfalls to be aware of.\n\n[^1]: The `lang` option [can be used](https://quarto.org/docs/authoring/language.html) to change the *overall* language of a website, but this does not allow selecting from among multiple languages.\n\n## Getting started\n\nHere, I assume you want to add multilingual support to an existing webpage. For demonstration purposes, let's use the default one generated by `quarto create project` (or `quarto_create_project()` if using the `quarto` R package):\n\n\n\n::: {.cell}\n\n:::\n\n::: {.cell}\n\n```{.r .cell-code}\nlibrary(quarto)\nlibrary(babelquarto)\nlibrary(fs)\n\n# Create the website in a temporary directory.\ntemp_dir <- tempdir()\n\nquarto_create_project(\n  name = \"example\",\n  type = \"website\",\n  dir = temp_dir\n)\n```\n:::\n\n\n\nLet's check the contents of the new website:\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nwebsite_dir <- path(temp_dir, \"example\")\n\ndir_tree(website_dir)\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n/var/folders/1f/5zb_w4bj03v5s6fzvqffj74c0000gn/T/RtmpWKUOvg/example\n├── _quarto.yml\n├── about.qmd\n├── index.qmd\n└── styles.css\n```\n\n\n:::\n:::\n\n\n\nIn subsequent steps we will modify `_quarto.yml`, so let's see what it looks like in its default form:\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nreadr::read_lines(path(website_dir, \"_quarto.yml\")) |>\n  cat(sep = \"\\n\")\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\nproject:\n  type: website\n\nwebsite:\n  title: \"example\"\n  navbar:\n    left:\n      - href: index.qmd\n        text: Home\n      - about.qmd\n\nformat:\n  html:\n    theme: cosmo\n    css: styles.css\n    toc: true\n```\n\n\n:::\n:::\n\n\n\n## Register languages\n\nThe next step is to modify `_quarto.yml` by registering the main language of the website (in other words, the default language that appears when accessing the main URL). Here, we will register Japanese as the main language:\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nregister_main_language(\n  main_language = \"ja\",\n  project_path = website_dir\n)\n```\n:::\n\n\n\nThis will modify `_quarto.yml`:\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nreadr::read_lines(path(website_dir, \"_quarto.yml\")) |>\n  cat(sep = \"\\n\")\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\nproject:\n  type: website\n\nwebsite:\n  title: \"example\"\n  navbar:\n    left:\n      - href: index.qmd\n        text: Home\n      - about.qmd\n\nformat:\n  html:\n    theme: cosmo\n    css: styles.css\n    toc: true\n\n\n\n\nbabelquarto:\n  languagecodes:\n  - name: ja\n    text: \"Version in ja\"\n  mainlanguage: 'ja'\nlang: ja\n```\n\n\n:::\n:::\n\n\n\nYou can see a new key `babelquarto` has been added at the end. We'll get to the details of that in a moment.\n\nNext, let's add an additional language. You can add as many additional languages as you like, but here we will only add English:\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nregister_further_languages(c(\"en\"), website_dir)\n\nreadr::read_lines(path(website_dir, \"_quarto.yml\")) |>\n  cat(sep = \"\\n\")\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\nproject:\n  type: website\n\nwebsite:\n  title: \"example\"\n  navbar:\n    left:\n      - href: index.qmd\n        text: Home\n      - about.qmd\n\nformat:\n  html:\n    theme: cosmo\n    css: styles.css\n    toc: true\n\n\n\n\nbabelquarto:\n  languagecodes:\n  - name: en\n    text: \"Version in en\"\n  - name: ja\n    text: \"Version in ja\"\n  mainlanguage: 'ja'\n  languages: ['en']\ntitle-en: title in en\ndescription-en: description in en\nauthor-en: author in en\nlang: ja\n```\n\n\n:::\n:::\n\n\n\n## Edit `_quarto.yml`\n\nSo far, `babelquarto` has generated files and content for us, but the next step is to get our hands dirty and actually edit `_quarto.yml`.\n\nWe will make the following changes:\n\n-   Change the text on the **language selector** {{< bi globe2 >}} from `Version in en` to `English` and `Version in ja` to `日本語`.\n\n-   Set the English versions of the homepage title, author, and description.\n\n-   Simplify the layout of the navbar (more on this later...)\n\nThis is what edited version looks like:\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\ngetwd()\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] \"/Users/joelnitta/repos/joelnitta-home/posts/2024-12-06_babelquarto\"\n```\n\n\n:::\n\n```{.r .cell-code}\nfs::file_copy(\n  path = \"./example-quarto.yml\",\n  path(website_dir, \"_quarto.yml\"),\n  overwrite = TRUE\n)\nreadr::read_lines(path(website_dir, \"_quarto.yml\")) |>\n  cat(sep = \"\\n\")\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\nproject:\n  type: website\n\nwebsite:\n  title: \"テスト用のサイト\"\n  navbar:\n    left:\n      - index.qmd\n      - about.qmd\n\nformat:\n  html:\n    theme: cosmo\n    css: styles.css\n    toc: true\n\n\n\n\nbabelquarto:\n  languagecodes:\n  - name: en\n    text: \"English\"\n  - name: ja\n    text: \"日本語\"\n  mainlanguage: 'ja'\n  languages: ['en']\ntitle-en: Test Site\ndescription-en: My test website\nauthor-en: Joel Nitta\nlang: ja\n```\n\n\n:::\n:::\n\n\n\n## Add translated files\n\nIt bears repeating that `{babelquarto}` renders multilingual websites, and does not actually *translate* any contents. So we need to provide those ourselves.\n\n`{babelquarto}` expects the translated files to be named with `.<lang>` inserted between the original file name and the `.qmd` extension. For example, the English version of `index.qmd` is `index.en.qmd`. In this example, `index.qmd` has contents in the default language (Japanese).\n\nOnce you've written out those files, the website folder should look like this:\n\n\n\n::: {.cell}\n\n:::\n\n::: {.cell}\n\n```{.r .cell-code}\ndir_tree(website_dir)\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n/var/folders/1f/5zb_w4bj03v5s6fzvqffj74c0000gn/T/RtmpWKUOvg/example\n├── _quarto.yml\n├── about.en.qmd\n├── about.qmd\n├── index.en.qmd\n├── index.qmd\n└── styles.css\n```\n\n\n:::\n:::\n\n\n\n...with (for example) contents like this:\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nreadr::read_lines(path(website_dir, \"index.qmd\")) |>\n  cat(sep = \"\\n\")\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n---\ntitle: \"ホーム\"\n---\n\nこれは Quarto のウェブサイトです。\n\nQuarto のウェブサイトについて詳しく知りたい場合は、<https://quarto.org/docs/websites> をご覧ください。\n```\n\n\n:::\n\n```{.r .cell-code}\nreadr::read_lines(path(website_dir, \"index.en.qmd\")) |>\n  cat(sep = \"\\n\")\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n---\ntitle: \"Home\"\n---\n\nThis is a Quarto website.\n\nTo learn more about Quarto websites visit <https://quarto.org/docs/websites>.\n```\n\n\n:::\n:::\n\n\n\n## Render\n\nNext, we need to render the `.qmd` files to HTML.\nIf you are used to using Quarto, you may expect to do this with `quarto render` or `quarto preview`, but those do not work with `babelquarto`.\n\nInstead, we use `babelquarto::render_website()`.\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nrender_website(project_path = website_dir)\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n\u001b[1m\u001b[34m\n[1/2] index.qmd\u001b[39m\u001b[22m\n\u001b[1m\u001b[34m\n[2/2] about.qmd\u001b[39m\u001b[22m\n\nOutput created: _site/index.html\n\n\u001b[1m\u001b[34m\n[1/2] index.qmd\u001b[39m\u001b[22m\n\u001b[1m\u001b[34m\n[2/2] about.qmd\u001b[39m\u001b[22m\n\nOutput created: _site/index.html\n```\n\n\n:::\n:::\n\n\n\nThe HTML has been written out to `_site/`.\n\n## Serve\n\nNow we'd like to view the rendered website in a browser.\nOnce again, `quarto preview` cannot be used here.\nInstead, use `servr::httw()`.\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nservr::httw(path(website_dir, \"_site\"))\n```\n:::\n\n\n\nYour browser should open a tab with the website shown below:\n\n<iframe src=\"https://joelnitta.github.io/example-babelquarto/\" width=\"100%\" height=\"400px\"></iframe>\n\n",
+    "supporting": [],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {},
+    "preserve": {},
+    "postProcess": true
+  }
+}