add lang query param and document it in contributing

CONTRIBUTING.md

@@ -144,6 +144,15 @@ See
 on how to get started, or jump right into translating at 
 [crowdin.com/project/electron](https://crowdin.com/project/electron).
 
+#### Sharing Localized URLs
+
+If you wish to share a URL linking to a translated page of the Electron website,
+add a `lang` param to the URL. This will override the visitor's existing 
+language preferences and display the given page in the specified language:
+
+Example: 
+[/docs/api/browser-window?lang=fr-FR](https://electronjs.org/docs/api/browser-window?lang=fr-FR)
+
 ## Routes
 
 Website routes are defined in [server.js](server.js).

middleware/context-builder.js

@@ -9,19 +9,21 @@ module.exports = function contextBuilder (req, res, next) {
   req.i18n = i18n
 
   // This allows the language to be set per-request using a query param, so
-  // folks can share a link like /docs/api/app?language=fr-FR and know that
+  // folks can share a link like /docs/api/app?lang=fr-FR and know that
   // the recipient will see the doc in that language, regardless of their
   // language settings. If no query param is set, fall back to the default
   // language (or the one set in the cookie)
-  const targetLanguage = req.query.language || req.language
+  if (req.query.lang) {
+    req.language = req.query.lang
+  }
 
-  const localized = i18n.website[targetLanguage]
+  const localized = i18n.website[req.language]
 
   // Page titles, descriptions, etc
   let page = Object.assign({
     title: 'Electron',
     path: req.path
-  }, i18n.website[targetLanguage].pages[req.path])
+  }, i18n.website[req.language].pages[req.path])
 
   if (req.path !== '/') {
     page.title = `${page.title} | Electron`
@@ -41,7 +43,7 @@ module.exports = function contextBuilder (req, res, next) {
   }
 
   if (req.path.startsWith('/docs')) {
-    req.context.docs = i18n.docs[targetLanguage]
+    req.context.docs = i18n.docs[req.language]
   }
 
   return next()

package.json

@@ -88,6 +88,7 @@
     "simplecrawler": "^1.1.6",
     "standard": "^10.0.3",
     "supertest": "^3.0.0",
+    "supertest-session": "^3.1.0",
     "walk-sync": "^0.3.2"
   },
   "engines": {

test/index.js

@@ -2,6 +2,7 @@ require('make-promises-safe')
 const { describe, it, beforeEach, afterEach } = require('mocha')
 const test = it
 const supertest = require('supertest')
+const session = require('supertest-session')
 const nock = require('nock')
 const cheerio = require('cheerio')
 const chai = require('chai')
@@ -275,11 +276,17 @@ describe('electronjs.org', () => {
     })
 
     test('language query param for one-off viewing in other languages', async () => {
-      let $ = await get('/docs/api/browser-window?language=fr-FR')
-      $('body').text().should.include('fenêtres')
+      const frenchContent = 'fenêtres'
+      const sesh = session(app)
 
-      $ = await get('/docs/api/browser-window')
-      $('body').text().should.not.include('fenêtres')
+      let res = await sesh.get('/docs/api/browser-window?lang=fr-FR')
+      let $ = cheerio.load(res.text)
+      $('blockquote').text().should.include(frenchContent)
+
+      // verify that the query param does not persist as a cookie
+      res = await sesh.get('/docs/api/browser-window')
+      $ = cheerio.load(res.text)
+      $('blockquote').text().should.not.include(frenchContent)
     })
   })