EDIT March 2019: this website is now based on WordPress, this article is kept as an archive<\/em><\/p>\n
EDIT : This method for translating DocPad is currently developped as a plugin<\/a> by Bernhard F.W. Gschaider ! Many thanks to him !<\/strong><\/p>\n
In my way building this website, one the major technical point to solve was internationalization and multilingual support. I want to publish in English and French, and maybe more languages when times comes.
\nBut for now (v6.64), Docpad<\/a>, the publishing system I choosed for this website, do not have any official localization abilities<\/a>.
\nSo here is a full description the solution I finally implemented today (took much more time than expected !).<\/p>\n
TL; DR;<\/h3>\n
No, sorry, I’m afraid there is no shortways.<\/p>\n
Table of content<\/h4>\n
\n
Thanks first<\/a><\/li>\n
How I like it to be<\/a><\/li>\n
The solution I ended up with<\/a>\n
\n
Structure<\/a><\/li>\n
Declaration<\/a><\/li>\n
Generate language specific Metadatas with collections<\/a><\/li>\n
Translation strings, and translation files in JSON Format<\/a>\n
\n
The translations functions<\/a><\/li>\n
Tell Docpad where are our translation files<\/a><\/li>\n<\/ul>\n<\/li>\n
Localize Dates<\/a><\/li>\n
Path and urls<\/a>\n
\n
Navigation and menus<\/a><\/li>\n
Collections of associated files<\/a><\/li>\n
Language switcher<\/a><\/li>\n<\/ul>\n<\/li>\n
Language redirection for visitors<\/a>\n
\n
Server side<\/a><\/li>\n
Client side<\/a><\/li>\n
Client side storage of prefered language<\/a><\/li>\n
The 404 case<\/a><\/li>\n<\/ul>\n<\/li>\n
Limits<\/a><\/li>\n<\/ul>\n<\/li>\n
Abstracting ?<\/a><\/li>\n<\/ul>\n
<\/a>Thanks first<\/h3>\n
I’m a designer, not a real coder, and my solution is heavily inspired by 3 already existing projets.
\nWithout their code available, I wouldn’t have achieved this work: many thanks for being open !<\/p>\n
In chronological order :
\n– Zeno Rocha’s Browser Diet<\/a> website
\n– Adam Pritchard’s Psiphon Circumvention System<\/a> website
\n– Artem Sapegin’s Blog<\/a><\/p>\n
I must also thanks Benjamin Lupton<\/a> for his work on Docpad, the needed infrastructure work, and the initial idea behind this solution.<\/p>\n
<\/a>How I like it to be<\/h3>\n
As you may have noticed, I host many, many images, they will grow, and I can’t aford to duplicate them, a major flaw IMHO in two of the previous mentionned already exiting solutions.
\nSo no duplication, or a minimum : duplicate only text, which you can’t avoid in a translation !<\/p>\n
My requierments were :
\n1. Minimal disk usage
\n2. KISS
\n3. translations strings available for templating (like @_ 'translate-me'<\/code>) with plural support \n4. localize dates \n5. Transparent visitor redirection, server side prefered \n6. SEO friendly (urls and titles in the correct language) \n7. do not mess too much with Docpad behavior, and let important plugins do their usual job (Clean URLs, tagging, partials…). \n8. generate every language in one go, with a simple docpad run<\/code> (no parameters like --lang-en<\/code>) \n9. Allow for translation services likeTransifex<\/a> to be used partially or fully. So JSON format for translation files. Artem Sapegin’s solution use YAMLjs instead.<\/p>\n
<\/a>The solution I ended up with<\/h2>\nI spend many days messing around with this code, and it’s not perfect. But it mostly do what I want so far. \nAs already mentioned in the footer of this website, my code is available on Github<\/a>, and it’s commented if you want to test an implementation or dig into it.<\/p>\n <\/a>Structure<\/h3>\nFirst of all, a structure. I tried to keep it as simple and near to an untranslated Docpad project as possible.<\/p>\nMy solution work by setting up language specific directories inside the documents<\/code> folder, which automatically force Docpad in using language specific subdirectories. \nThis mean visitors will always see the subdirectories in your URLS, like example.com\/en\/<\/code> or example.com\/fr\/<\/code>. Yes, even for your base language (often english). \nIf you don’t want subdirectories, this is not for you. You may try Artem Sapegin’s solution<\/a> if you want to publish into subdomains or differents domains, or try to adapt my solution to your context with some Express.js server-side redirection.<\/p>\n So, your project structure must look like this one : \n– docpad-project \n– src \n– documents \n– en \n– blog \n– other-category \n– fr \n– blog \n– other-category \n– any-language \n– blog \n– other-category \n– scripts \n– styles \n– files \n– layouts \n– out<\/p>\n With one document subdirectory for each language, even the base one. You can place a document directly in documents<\/code> root, but it must not call translation functions, and it won’t be translated.<\/p>\n If you want to keep things simple, a limit is that if you want to get collections of documents into sub-subdirectories like blog<\/code> from your layouts, thoses sub-subdirectories must have the same name in every language . Not really a problem in my case, because blog<\/code> and img<\/code> can be untranslated. One way to have a workaround may be to use metadatas instead of sub-subdirectories for your categories (cat: 'My category'<\/code>), and another is to use the navigation menu trick I will explain later.<\/p>\n Note that the file<\/code> directory remain untouched. That’s on purpose, to avoid duplication of files and blobs especially.<\/p>\n Additionnaly, you can create a lang<\/code> or locale<\/code> directory somewhere, to put your translation files into it. In my case I choosed not to have one more subdirectory, and I put my translation file directly in the corresponding folder, for example documents\/en\/en.json<\/code> and documents\/fr\/fr.json<\/code><\/p>\n Right now, you can start translating files into each subdirectory, and it will work. But that’s limited because Docpad still have no idea of what we do.<\/p>\n <\/a>Declaration<\/h3>\nSecond step is to tell Docpad what we expect from it to do on this front.<\/p>\n So, open docpad.coffee<\/code> or your docpad configuration file and start to declare :<\/p>\ntemplateData:\r\n\r\n # -----------------------------\r\n # Language Definition\r\n\r\n # List all available languages here\r\n # Must match with a corresponding directory in src\/documents\/\r\n languages: ['en', 'fr']\r\n\r\n # Define default language\r\n default_lang: 'en'\r\n\r\n # Define plural for each language. A list is available here :\r\n # https:\/\/github.com\/airbnb\/polyglot.js\/blob\/master\/lib\/polyglot.js\r\n # (don't forget to convert to coffeescript !)\r\n plural_types:\r\n en: (n) -> (if n isnt 1 then 1 else 0)\r\n fr: (n) -> (if n > 1 then 1 else 0)\r\n\r\n # Translation file location\r\n # Depending on your translation system, you may want to change that\r\n # remember this path start from the docpad directory\r\n translation_files:\r\n en: 'src\/documents\/en\/en.json'\r\n fr: 'src\/documents\/fr\/fr.json'\r\n\r\n # Translations will be loaded into this object. Required.\r\n translations: {}\r\n<\/code><\/pre>\nand you can continue with your classical template datas :<\/p>\n # -----------------------------\r\n # Non translated definitions (untranslated names, urls ..)\r\n site:\r\n # The production url of our website\r\n url: \"http:\/\/nylnook.com\"\r\n\r\n # Here are some old site urls that you would like to redirect from\r\n oldUrls: [\r\n 'www.nylnook.com'\r\n ]\r\n\r\n # The default title of our website\r\n title: \"nylnook\"\r\n\r\n # The website author\r\n author: \"Camille Bissuel\"\r\n<\/code><\/pre>\nOk, we have done some declaration, but so what ? Next, use them.<\/p>\n<\/a>Generate language specific Metadatas with collections<\/h3>\nNext step is to automatically build language metadatas for every document in every language. That’s sound crazy, but this is the only reliable method to be able to easily know what is the current language in any document. With this, a simple @document.lang<\/code> (with eco templating) will give us the current language.<\/p>\n Thanks again to Adam Pritchard, this is almost a copy-and-paste from his work :<\/p>\n # =================================\r\n # Collections\r\n collections:\r\n # This is internationalized, and only to build automatic template data !!!\r\n # If you try to use it in your files, you will obtain all results in every language\r\n # In your templates, use for example\r\n # @getCollection(\"html\").findAllLive({relativeOutDirPath: @document.lang+'\/blog'},[{date:-1}])\r\n # instead of thoses collections\r\n\r\n # This collection is absolutely required to make internationalization work !\r\n # this wil add a \"lang\" metadata correponding to the same directory to each file in documents\r\n setlangforalldocuments: (database) ->\r\n lang_dirs = ('\/'+lang+'\/' for lang in @config.templateData.languages)\r\n lang_regex = ('^'+lang_dir for lang_dir in lang_dirs).join('|')\r\n\r\n @getCollection('documents').createChildCollection()\r\n .setFilter 'search', (model) ->\r\n return false if not model.get('url')\r\n\r\n lang_match = model.get('url').match(lang_regex)\r\n return false if not lang_match\r\n\r\n lang = lang_match[0].replace(\/^\\\/|\\\/$\/g, '')\r\n model.setMetaDefaults { lang: lang }\r\n true\r\n<\/code><\/pre>\nAnd you can continue with this technic to generate other metadatas, in this example a layout<\/p>\n # Build template data for posts (only relative path and metadata change)\r\n posts: (database) ->\r\n lang_dirs = ('\/'+lang+'\/blog' for lang in @config.templateData.languages)\r\n lang_regex = ('^'+lang_dir for lang_dir in lang_dirs).join('|')\r\n\r\n @getCollection('documents').createChildCollection()\r\n .setFilter 'search', (model) ->\r\n return false if not model.get('url')\r\n\r\n lang_match = model.get('url').match(lang_regex)\r\n return false if not lang_match\r\n\r\n lang = lang_match[0].replace(\/^\\\/|\\\/$\/g, '')\r\n model.setMetaDefaults { layout:\"post-layout\"}\r\n true\r\n<\/code><\/pre>\nThis is the core of our solution<\/strong>. This is absolutelly needed to make translation work.<\/p>\nBut this mean you cannot use anymore in your templates nice calls like the one explained in the Docpad Beginner guide<\/a> :<\/p>\n <% for posts in @getCollection(\"posts\").toJSON(): %>\r\n<\/code><\/pre>\nbecause this wil send you every post in every language. \nBut instead you will have to use less nice ones like (note the relativeOutDirPath: @document.lang+'\/blog'<\/code> parameter) :<\/p>\n<% for posts in @getCollection(\"html\").findAllLive({relativeOutDirPath: @document.lang+'\/blog'},[{date:-1}]).toJSON(): %>\r\n<\/code><\/pre>\nThat’s ok, but I don’t know what it does on the preformance side. For now, I didn’t noticed any difference.<\/p>\n<\/a>Translation strings, and translation files in JSON Format<\/h3>\nIn our templates at least, we want to be able to translate any sentence in the correct language. We will do that by replacing text with a call to a translation function.<\/p>\n So HTML<\/p>\n<\/code><\/pre>\nI want to translate this sentence<\/p>\n<\/code><\/pre>\nwill become (with Eco)<\/p>\n<\/code><\/pre>\n<%- @_ ‘I want to translate this sentence’ %><\/p>\n<\/code><\/pre>\nor shortly<\/p>\n<\/code><\/pre>\n<%- @_ ‘sentence_key’ %><\/p>\n<\/code><\/pre>\nYou can add variables into it<\/p>\n<\/code><\/pre>\n<%- @_ ‘The answer is’, num: 42 %><\/p>\n<\/code><\/pre>\nAnd even use the plural<\/p>\n <\/code><\/pre>\n<%- @_ ‘posts-number’, num: documents.length, posts: @plural(documents.length, ‘post|posts’) %><\/p>\n <\/code><\/pre>\nThe translation is send to JSON, so characters you must escape with a \\<\/code> are the \\<\/code> itself and \"<\/code><\/p>\n But until now there is no corresponding translation file to our calls, and our sentences will not be translated (they will appear as they are). So we must create the files we declared before.<\/p>\n In my case documents\/en\/en.json<\/code><\/p>\n {\r\n \"sentence_key\" : \"I want to translate this sentence\",\r\n \"The answer is\": \"The answer is {num}\",\r\n \"post|posts\" : \"post|posts\",\r\n \"posts-number\" : \"{num} {posts}\"\r\n\r\n}\r\n<\/code><\/pre>\nand documents\/fr\/fr.json<\/code><\/p>\n {\r\n \"sentence_key\" : \"Je veux traduire cette phrase\",\r\n \"The answer is\": \"La r\u00e9ponse est {num}\",\r\n \"post|posts\" : \"article|articles\",\r\n \"posts-number\" : \"{num} {posts}\"\r\n\r\n}\r\n<\/code><\/pre>\n<\/a>The translations functions<\/h4>\nbut as is Docpad will send you errors if we don’t add the translations functions in docpad.coffee<\/code> templateData<\/p>\n templateData:\r\n # ...\r\n\r\n # Translate the given key into the language of the current document.\r\n # Fallback to default language if the key if not found or fallback again to unstranslated string.\r\n # You can use simple variables: @_ 'The answer is', num: 42 \r\n _: (key, translations_with_parameters=null) ->\r\n translations_with_parameters ?= []\r\n if @translations[@document.lang][key]?\r\n message = @translations[@document.lang][key]\r\n else if @translations[@default_lang][key]?\r\n message = @translations[@default_lang][key]\r\n else\r\n message = key\r\n message.replace \/\\{([^\\}]+)\\}\/g, (translation, param) ->\r\n translations_with_parameters[param] or translation\r\n\r\n # Plural form for translations\r\n # Fallback to default language if the key if not found or fallback again to unstranslated string.\r\n # Simple example : @plural(3, 'dog|dogs')\r\n # Example in context : @_ '{num} {posts}', num: documents.length, posts: @plural(documents.length, 'post|posts')\r\n plural: (n, key) ->\r\n if @translations[@document.lang][key]?\r\n return ((@_ key).split '|')[@plural_types[@document.lang](n)]\r\n else if @translations[@default_lang][key]?\r\n return ((@_ key).split '|')[@plural_types[@default_lang](n)]\r\n else\r\n return ((@_ key).split '|').slice(0,1)\r\n\r\n # ...\r\n<\/code><\/pre>\n<\/a>Tell Docpad where are our translation files<\/h4>\nThat’s not enough… Docpad need to load our translation files before starting to render documents ! \nSo we add a dedicated event :<\/p>\n # =================================\r\n # DocPad Events\r\n\r\n # Here we can define handlers for events that DocPad fires\r\n # You can find a full listing of events on the DocPad Wiki\r\n events:\r\n\r\n # We add this event to load the translations from locale JSON files\r\n renderBefore: (opts, next) ->\r\n fs = require 'fs'\r\n\r\n for lang of opts.templateData.translation_files\r\n langJSON = fs.readFileSync opts.templateData.translation_files[lang]\r\n try\r\n opts.templateData.translations[lang] = JSON.parse(langJSON)\r\n catch error\r\n console.log \"\\n\\nERROR: Language JSON fail: #{lang}: #{error}\\n\"\r\n throw error\r\n\r\n next()\r\n<\/code><\/pre>\nRemember we have declared their relative urls in the templateData<\/code> part earlier.<\/p>\nAnd the magic can happen… translated strings !<\/p><\/blockquote>\n<\/a>Localize Dates<\/h3>\nNext step is to localize dates. We will need the essential Moment.js<\/a> library to manage that with beauty.<\/p>\n So, let’s install it :<\/p>\n npm install --save moment\r\n<\/code><\/pre>\nAnd let’s add 2 more functions in our docpad.coffee templateData<\/code> :<\/p>\n templateData:\r\n # ...\r\n\r\n # Returns a human readable formatted date. Require Moment.js\r\n # Example : @date()\r\n # Example with parameters : @date(post.date, post.lang)\r\n date: (date, lang) ->\r\n if not date\r\n date = @document.date\r\n if not lang\r\n lang = @document.lang\r\n moment = require 'moment'\r\n moment.lang(lang)\r\n return moment(date).format('LL');\r\n\r\n # Returns a computer readable formatted date. Require Moment.js\r\n # Example : @computerDate()\r\n # Example with parameters : @computerDate(post.date)\r\n # Example in HTML5: <time pubdate=\"<%- @computerDate() %>\"><%- @date() %><\/time>\r\n computerDate: (date) ->\r\n if not date\r\n date = @document.date\r\n moment = require 'moment'\r\n return moment(date).format('YYYY-MM-DD');\r\n\r\n # ...\r\n<\/code><\/pre>\nin our templates, we will just put<\/p>\n<time pubdate=\"<%- @computerDate() %>\"><%- @date() %><\/time>\r\n<\/code><\/pre>\nTo get a localized date. Please adjust the format<\/code> as mentioned on Moment.js website<\/a> to suit your needs.<\/p>\n To use dates in a call for a collections, we will just add parameters<\/p>\n <% for post in @getCollection(\"html\").findAllLive({relativeOutDirPath: @document.lang+'\/blog'},[{date:-1}]).toJSON(): %>\r\n <article class=\"post\">\r\n <h2><a href=\"<%= post.url %>\"><%- post.title %><\/a><\/h2>\r\n <time pubdate=\"<%- @computerDate(post.date) %>\"><%- @date(post.date, post.lang) %><\/time>\r\n <%- post.contentRenderedWithoutLayouts %>\r\n <\/article>\r\n<% end %>\r\n<\/code><\/pre>\nOk for dates, thank you Moment.js !<\/p><\/blockquote>\n<\/a>Path and urls<\/h3>\nAdditionally, you may want to create link to your images, or to any file. \nGood news is that’s quite easy : just use relative urls, and do not forget to go one parent directory earlier in your paths.<\/p>\n If your document path is for example \/en\/blog\/this-post.html<\/code> \nthe path to your file will be at<\/p>\n..\/..\/img\/mypicture.jpg\r\n<\/code><\/pre>\nIf you absolutely need to parse url, here are 2 relatively useless functions for reference, but I finally removed them in my case, they were unused, and bad for performances.<\/p>\n templateData:\r\n # ...\r\n # Allow to obtain current language from URL if @document.lang isn't available\r\n # Using @document.lang is prefered for performance\r\n langFromPath: (document) ->\r\n if not document\r\n document = @document\r\n return document.relativeDirPath.split('\/').slice(0,1)\r\n\r\n # Get a path without current language. Maybe useful in templates to get a file path\r\n # Example : <%= @pathWithoutLang(post) %>\r\n pathWithoutLang: (document) ->\r\n if not document\r\n document = @document\r\n return document.relativeOutDirPath.split('\/').slice(1)\r\n<\/code><\/pre>\n<\/a>Navigation and menus<\/h4>\nThe tricky part is when you want to link to a corresponding document in another language. For example, you have a navigation menu refering to<\/p>\ndocuments\/en\/about.html\r\n<\/code><\/pre>\nin english<\/p>\n and to<\/p>\ndocuments\/fr\/a-propos.html\r\n<\/code><\/pre>\nin french.<\/p>\n We may use the same filename in every language, and just change the lang path :<\/p>\ndocuments\/<%- @document.lang %>\/about.html\r\n<\/code><\/pre>\nBut remember we want to be SEO friendly, so path name should be similar to titles names in the corresponding language.<\/p>\n The simplest solution I found is to add additional “key”:”value” in our translations files.<\/p>\n in en.json<\/p>\n{\r\n \"about\": \"About\",\r\n \"about-filename\": \"about\"\r\n}\r\n<\/code><\/pre>\nin fr.json<\/p>\n{\r\n \"about\": \"\u00c0 propos\",\r\n \"about-filename\": \"a-propos\"\r\n}\r\n<\/code><\/pre>\nSo the link in our template become :<\/p>\n<a href=\"\/<%- @document.lang %>\/<%= @_ 'about-filename' %>\"><%= @_ 'about' %><\/a>\r\n<\/code><\/pre>\nIf your navigation is quite short (6 entries in my case), which is a good idea anyway, this is ok. \nBut you will have to find another solution if you have a lot. See Adam Pritchard’s solution<\/a> maybe.<\/p>\n <\/a>Collections of associated files<\/h4>\nAs a side note to path management, the associatedfiles Docpad plugin<\/a> will not work anymore with this internationalization solution.<\/p>\n Replace it simply with this kind of templating (@getFilesAtPath<\/code> is a Docpad function) :<\/p>\n <% for file in @getFilesAtPath('..\/..\/img\/gallery').toJSON(): %>\r\n\r\n<% end %>\r\n<\/code><\/pre>\n<\/a>Language switcher<\/h4>\nThat’s not the strongest part of my code, but in my case I wanted it very simple, so here it is, in a template :<\/p>\n<\/code><\/pre>\n<%- @document.lang %><\/a> <% for lang in @languages : %> <% if lang isnt @document.lang : %> ” ><%- lang %><\/a> <% end %> <% end %><\/nav>\n<\/code><\/pre>\n <\/p>\n<\/code><\/pre>\nAnd no functions at all.<\/p>\n Yes, that mean there is no way for a visitor to switch from a blog post in a language to the same blog post in another language. A visitor will always have to go back to home page…<\/p>\n But are you constantly switching language when you visit a website ? \nI simply suppose the behavior is : \n1. land on the website in a language (correctly detected from visitor browser preferences if possible) \n2. switch language if it doesn’t suit \n3. visit and never change the language again<\/p>\n So I don’t need complex functions and a lot of metadatas everywhere just to handle a marginal case.<\/p>\n And if a correspondance is absolutely needed somewhere, use the menu trick mentionned before.<\/p>\n<\/a>Language redirection for visitors<\/h3>\n<\/a>Server side<\/h4>\nSo, we want visitors to land in the best language according to their preference. \nIf possible, we want to do that server side to avoid the “no-script” user case.<\/p>\n Good news once again, if we have a dynamic server, it’s possible ! Furthermore, it’s my case. \nThe main idea is to use the req.headers[\"accept-language\"]<\/code> Express.js function to detect our vistor HTTP header.<\/p>\nTo have a robust and simple code, we will use the Negociator library<\/a>.<\/p>\n Installation :<\/p>\n npm install --save negociator\r\n<\/code><\/pre>\nand in the event section of docpad.coffee<\/code> we will add a second part to the classic serverExtend<\/code> event :<\/p>\n events:\r\n\r\n #...\r\n\r\n\r\n # Server Extend\r\n # Used to add our own custom routes to the server before the docpad routes are added\r\n serverExtend: (opts) ->\r\n # Extract the server from the options\r\n {server} = opts\r\n docpad = @docpad\r\n\r\n # As we are now running in an event,\r\n # ensure we are using the latest copy of the docpad configuraiton\r\n # and fetch our urls from it\r\n latestConfig = docpad.getConfig()\r\n oldUrls = latestConfig.templateData.site.oldUrls or []\r\n newUrl = latestConfig.templateData.site.url\r\n\r\n\r\n # Redirect any requests accessing one of our sites oldUrls to the new site url\r\n server.use (req,res,next) ->\r\n if req.headers.host in oldUrls\r\n res.redirect(newUrl+req.url, 301)\r\n else\r\n next()\r\n\r\n\r\n # We add this event to redirect visitor reaching root domain to their prefered language\r\n # at the corresponding subdomain.\r\n # We use the \"Accept-Language\" header for that. Require the \"negociator\" npm package\r\n # If negociator fail to find any solution, default language is used\r\n\r\n # \/!\\ This will not work if the server is static !\r\n # If static, use an index.html file with client side javascript detection to replace this.\r\n # Example script in \/src\/documents\/404.hml.eco\r\n server.use (req,res,next) ->\r\n if req.path == \"\/\"\r\n Negotiator = require('negotiator')\r\n negotiator = new Negotiator(req)\r\n available_languages = latestConfig.templateData.languages\r\n if (!!negotiator.language(available_languages))\r\n #console.log('redirect to \/' + negotiator.language(availableLanguages))\r\n res.redirect(negotiator.language(available_languages))\r\n else\r\n #console.log('redirect to default language')\r\n res.redirect(latestConfig.templateData.default_lang)\r\n else\r\n next()\r\n<\/code><\/pre>\nSo, if a visitor hit the root domain, he is redirected to the best language we can find for him, or to the default one.<\/p>\n<\/a>Client side<\/h4>\nIf you can’t do server-side redirection because your server is static or you render static files, client side redirection is required. \nCreate an index.html<\/code> file at the documents<\/code> root, with this script (by Adam Pritchard) :<\/p>\n<script>\r\n var defaultLanguage, supportedLanguages, language, redirectLanguage;\r\n\r\n defaultLanguage = 'en';\r\n supportedLanguages = <%- JSON.stringify @languages %>;\r\n redirectLanguage = defaultLanguage;\r\n\r\n try {\r\n language = window.navigator.userLanguage || window.navigator.language || defaultLanguage;\r\n\r\n \/\/ Some languages we support look like 'en' and some like 'en-US'. Some languages\r\n \/\/ set in navigator.language look like 'en' and some like 'en-US'. So we'll\r\n \/\/ check both combinations.\r\n\r\n if (supportedLanguages.indexOf(language) >= 0) {\r\n redirectLanguage = language;\r\n }\r\n else if (supportedLanguages.indexOf(language.substr(0, 2)) >= 0) {\r\n redirectLanguage = language.substr(0, 2);\r\n }\r\n }\r\n catch (e) {\r\n \/\/ Really old Internet Explorer seems to throw an exception on the above code.\r\n \/\/ We'll just catch and pass.\r\n }\r\n\r\n \/\/ Redirect to a language-specific index page\r\n window.location.href = '\/' + redirectLanguage + '\/index.html';\r\n<\/script>\r\n<\/code><\/pre>\nand a fallback link to default language for the “no script” visitor. Remember that you can’t add any translation function in this file, this will result in an ‘undefined’ error.<\/p>\n<\/a>Client side storage of prefered language<\/h4>\nNot done yet… Plan to use the lawnchair<\/a> library.<\/p>\n <\/a>The 404 case<\/h4>\nIf a visitor go to a missing url, what happen ? How to redirect him to a page in his language ?<\/p>\nWe can’t rely on the urls he will use, nor on any metadata. So we are back again with language redirection, server side or client side. \nUnfortunatelly, a Docpad bug<\/a> prevent us to do any server side 404 redirection, because setting middleware404: false<\/code> in docpad.coffee<\/code> results in a long node.js Type error.<\/p>\n So we use a client side redirection : \nput a 404.html file at the documents<\/code> root with this script :<\/p>\n <script>\r\n var defaultLanguage, supportedLanguages, language, redirectLanguage;\r\n\r\n defaultLanguage = 'en';\r\n supportedLanguages = <%- JSON.stringify @languages %>;\r\n redirectLanguage = defaultLanguage;\r\n\r\n try {\r\n language = window.navigator.userLanguage || window.navigator.language || defaultLanguage;\r\n\r\n \/\/ Some languages we support look like 'en' and some like 'en-US'. Some languages\r\n \/\/ set in navigator.language look like 'en' and some like 'en-US'. So we'll\r\n \/\/ check both combinations.\r\n\r\n if (supportedLanguages.indexOf(language) >= 0) {\r\n redirectLanguage = language;\r\n }\r\n else if (supportedLanguages.indexOf(language.substr(0, 2)) >= 0) {\r\n redirectLanguage = language.substr(0, 2);\r\n }\r\n }\r\n catch (e) {\r\n \/\/ Really old Internet Explorer seems to throw an exception on the above code.\r\n \/\/ We'll just catch and pass.\r\n }\r\n\r\n \/\/ Redirect to a language-specific index page\r\n window.location.href = '\/' + redirectLanguage + '\/404.html';\r\n<\/script>\r\n<\/code><\/pre>\nand a fallback link to default language for the “no script” visitor. Remember that you can’t add any translation function in this file, this will result in an ‘undefined’ error.<\/p>\n Plus create a translated 404 files in each document language : they can be translated \nSo the visitor will see the error in the detected language : arguably it’s better than “english only”.<\/p>\nWorking examples : \n– documents\/404.html<\/a> \n– documents\/en\/404.html<\/a> \n– documents\/fr\/404.html<\/a><\/p>\n <\/a>Limits<\/h3>\nThe main one : this a subdirectory only solution.<\/p>\nAdditionally to the 404 bug, two Docpad plugins at least break with this internationalization solution : associatedfiles<\/a> and docpad-plugin-moment<\/a>.<\/p>\n And I didn’t test right-to-left or non-latin languages yet. So this code probably miss some declarations and functions to make them work. Adam Pritchard’s Psiphon Circumvention System<\/a> website contain some, if you want to dig into that.<\/p>\n <\/a>Abstracting ?<\/h2>\nWith some abstration to manage the subdomain and other domains cases, all this may go into a Docpad plugin to simplify installation… But I’m afraid I’m not the good guy for that… Remember : I’m a designer, not really a coder !<\/p>\n Let’s dream : some bits of this code may even be part of Docpad one day. No modesty here ;p<\/p>\n","protected":false},"excerpt":{"rendered":" EDIT March 2019: this website is now based on WordPress, this article is kept as an archive EDIT : This method for translating DocPad is currently developped as a plugin by Bernhard F.W. Gschaider ! Many thanks to him ! In my way building this website, one the major technical point to solve was internationalization […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"godot_game_meta":[],"pulp_press_meta":[],"pulp_comic_meta":[],"inline_featured_image":false,"nylnook_wp_meta":[null],"footnotes":""},"categories":[1],"tags":[31,52],"class_list":["post-86","post","type-post","status-publish","format-standard","hentry","category-blog","tag-geek","tag-tutorials"],"_links":{"self":[{"href":"https:\/\/nylnook.art\/en\/wp-json\/wp\/v2\/posts\/86","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/nylnook.art\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/nylnook.art\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/nylnook.art\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/nylnook.art\/en\/wp-json\/wp\/v2\/comments?post=86"}],"version-history":[{"count":3,"href":"https:\/\/nylnook.art\/en\/wp-json\/wp\/v2\/posts\/86\/revisions"}],"predecessor-version":[{"id":260,"href":"https:\/\/nylnook.art\/en\/wp-json\/wp\/v2\/posts\/86\/revisions\/260"}],"wp:attachment":[{"href":"https:\/\/nylnook.art\/en\/wp-json\/wp\/v2\/media?parent=86"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/nylnook.art\/en\/wp-json\/wp\/v2\/categories?post=86"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/nylnook.art\/en\/wp-json\/wp\/v2\/tags?post=86"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}