DEV Community: Israel Muñoz

Tutorial: International API - i18n + validation in Node.js' Express

Israel Muñoz — Mon, 04 Mar 2019 08:04:41 +0000

This post was originally published on israelmuca.dev

Recently, I was working on a project that has an i18n requirement. I needed the API to validate incoming user data, and depending on that data, return the specific success or error messages in the user’s provided language.

Regarding the actual translations, I wanted to easily provide the backend with the messages in both languages (Spanish and English to begin with), and I wanted to be able to eventually support more languages, being able to hire a translator if needed, and having him modify them “on the go” without requiring help from a developer.

So I started researching how to fulfill those requirements, and I ran into some hiccups along the way, thus, I thought it’d be nice to create a tutorial with my proposed (and implemented) solution.

Let’s code!

This tutorial uses ES6, Node.js and Express, creating a server that will be responding the calls.
I’ve included a working solution with basic testing, you can go ahead and check that out in this repository, or work through the code step-by-step with me!

Libraries

We’ll be using some battle tested libraries to speed up our development:

express, to create/manage the server
express-locale, to get the user’s locale
body-parser, to get the user’s input
express-validator, to validate the user’s input
node-polyglot, by Airbnb, to help us manage languages
object.fromentries, to convert an Array into an Object

And since we’ll be using ES6, we’ll also be needing babel!

@babel/cli
@babel/core
@babel/preset-env

So let’s get to the console and create the project

mkdir i18n-validation
cd i18n-validation
npm init

For this use case, we'll leave all the defaults that npm gives us, except for the default entry which I changed to server.js

Now, lets install our main dependencies

npm i express express-locale body-parser express-validator node-polyglot object.fromentries

Now, let’s install our development dependencies

npm i @babel/cli @babel/core @babel/preset-env --save-dev

Now, all we need to do is add another file:

touch .babelrc

And inside, we’ll write:

{
    "presets": [
        "@babel/preset-env"
    ]
}

If you’re going to source control your project, don ’t forget to add a .gitignore with node_modules in it, to avoid committing them.

Remember that we'll be using ES6, and we need to do some extra steps to be able to do so, so let's go ahead and change our scripts in the package.json:

{
...
  "main": "server.js",
  "scripts": {
    "clean": "rm -rf dist && mkdir dist",
    "transpile": "babel -d ./dist ./src",
    "build": "npm run clean && npm run transpile",
    "start": "npm run build && node ./dist/server.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
...
}

We’re using several scripts and daisy-chaining some of them.

clean to create the dist folder that will hold the ES5 transpiled code.

transpile to transpile the code from ES6 to ES5.

build runs clean and afterwards, transpile.

start runs build and afterwards, the server.js file with node from the new ES5 transpiled dist folder.

test is empty and won't be covered in the tutorial, but the repository includes basic tests.

Finally, let’s create the src folder and inside, the server.js file:

mkdir src
cd src
touch server.js

Let’s now get express going by modifying the server.js

// Import dependencies
// =============================================================
import express from 'express'

// Setup the express router
// =============================================================
const router = express()

// Set the port to be used
const port = process.env.PORT || 8080

// Start the server!
// =============================================================
router.listen(port, () => {
    console.log(`App running on port ${port}`)
})

By now, we can run:

npm start

If all’s good, the console should be telling us that we’re running on port 8080.
And with that, we’ll have a server… that does nothing!

Now, we need to actually get it going.

So we need to add more dependencies:

// Import dependencies
// =============================================================
import express from 'express'
import createLocaleMiddleware from 'express-locale'
import bodyParser from 'body-parser'

And we need to set them up on the server

// Setup the express router
// =============================================================
const router = express()

// Set the port to be used
const port = process.env.PORT || 8080

// Add data parsing to express
router.use(bodyParser.urlencoded({ extended: true }))
router.use(bodyParser.json())

// Get the user's locale, and set a default in case there's none
router.use(createLocaleMiddleware({
    "priority": ["accept-language", "default"],
    "default": "en_US"
}))

With these changes, now we’re checking on the user’s locale and parsing the data they’re sending. However, we need to add polyglot to express.

For that, we’ll first be creating our .js file where the translations will be living

mkdir i18n
cd i18n
touch i18n.js
cd ..

Let’s open this new file, where we’ll have two constants, an array that will show what languages are available

export const availableLangs = ['es', 'en']

And an object that will contain the actual translations

export const messages = {
    en: {
        // Error messages
        'emailRequiredField': "'email' is a required field.",
        'emailIsEmail': "This is not a valid email address.",
        'passwordRequiredField': "'password' is a required field.",

        // Success messages
        'loginSuccessful': "You've successfully logged in.",
        'emailSent': "Your password recovery email was sent."
    },
    es: {
        // Mensajes de error
        'emailRequiredField': "'email' es un campo requerido.",
        'emailIsEmail': "Este no es un email válido.",
        'passwordRequiredField': "'password' es un campo requerido.",

        // Mensajes de éxito
        'loginSuccessful': "Has iniciado sesión exitosamente.",
        'emailSent': "Tu correo de recuperación de contraseña ha sido enviado."
    }
}

With our messages ready, we’ll go ahead and create a middleware for express, that will import polyglot and these translations, to include them in the actual express request.

mkdir utilities
cd utilities
touch startPolyglot.js
cd ..

Open this new file, where we’ll import both polyglot and the translations

import Polyglot from 'node-polyglot'
import { messages } from '../i18n/i18n'

And we’ll create a function that will be used on every request as an Express’ middleware. It will get the user’s locale (which we got in the server.js), create an instance of Polyglot, and load it with the proper messages depending on the user’s language

exports.startPolyglot = (req, res, next) => {
    // Get the locale from express-locale
    const locale = req.locale.language

    // Start Polyglot and add it to the req
    req.polyglot = new Polyglot()

    // Decide which phrases for polyglot
    if (locale == 'es') {
        req.polyglot.extend(messages.es)
    } else {
        req.polyglot.extend(messages.en)
    }

    next()
}

If you remember, our server.js uses the createLocaleMiddleware to set the current locale, which lives on req.locale.language.

So we get that value, and for our use case, check if it is es for Spanish or en for English (our default in case it’s neither), and load the proper messages for the language, which are added to the Express’ ‘req’ object through polyglot’s extend function.

Adding Polyglot to Express

Now, we need to add this middleware to Express on the server.js, both by importing it, and adding it AFTER we create the locale middleware, as polyglot uses it.

import { startPolyglot } from './utilities/startPolyglot'

Add this line at the very top, with the rest of the imports.

// Start polyglot and set the language in the req with the phrases to be used
router.use(startPolyglot)

Add this lines after the createLocaleMiddleware function is called.

There, now our server is ready to send error or success messages in either Spanish or English, however, where will these messages originate?

Routes

So Express needs to know what to do with the different type of calls on the different routes.
For that, we’ll start listening for calls in our server by first creating a routes folder and file.

mkdir routes
cd routes
touch auth.routes.js
cd ..

Let’s open this file and add the following code:

// Routes =============================================================
module.exports = router => {

    // POST route to mock a log endpoint
    router.post("/api/login")

    // POST route to mock a forgotten password endpoint
    router.post("/api/forgot-password")
}

What this code will do, is export a function that will take the Express instance as a parameter to create the actual routes we’ll be using in our test API. For now, it’s missing parameters, since it’s only adding the first one, which tells express the route to listen to. After that parameter, we may add as many Express’ middlewares as we need. We will be adding middleware to do the input data validation, the error processing in case there’s any, and finally, if all’s good, respond with a success message if there were no errors with the validation.

Now, let’s go ahead and add it to the server.js right before we start it

// Routes
// =============================================================
require("./routes/auth.routes")(router)

This line should be added right before we start our server with router.listen

So now our API is listening for POST requests on localhost:8080/api/login and localhost:8080/api/forgot-password, but we still have no functionality, let’s get there.

Validating user’s input

So it’s time to validate data, for that, we’ll be using express-validator, which is a handy middleware that lets us validate data as it comes from the req object, setting specific error messages for each of the parameters that we’re expecting.

mkdir validator
cd validator
touch auth.validator.js
cd ..

Now, open auth.validator.js and we’ll first import the check function from express-validator.

import { check } from 'express-validator/check'

Next, we’ll create a function that will be exported, which we’ll be using as middleware in our auth.routes.js. This function receives a String, which we define based on the use case of that route, inside we’ll use the check function that was just imported, to validate the data we’re receiving.
We’ll be using a switch for that, so we can reuse the same validator both for the login, and the forgot-password.

Here’s the code:

exports.validator = functionName => {

    switch (functionName) {

        case 'login': {
            return [
                check('email')
                    .exists().withMessage('emailRequiredField')
                    .isEmail().withMessage('emailIsEmail'),

                check('password')
                    .exists().withMessage('passwordRequiredField')
            ]
        }

        case 'forgotPassword': {
            return [
                check('email')
                    .exists().withMessage('emailRequiredField')
                    .isEmail().withMessage('emailIsEmail')
            ]
        }
    }

}

We won’t go deep into the details of how the check function works, but it basically adds another object inside of the req which will store the errors (if there’s any).

What’s important to note though, is the fact that instead of setting normal error messages, we’re using the variables that we created on our i18n file!

Why? Because we want to use those keys from our i18n.js in whatever language the user chooses, so we need to check the object for all the possible error messages, and check our translated errors object, and swap the error string with the actual error message that we wrote in the user’s language... but not yet.

For now, we’ll be adding this validator into our route file by going to auth.routes.js and importing it:

import { validator } from '../validator/auth.validator'

This line should go at the very top, before our module.exports

Now, we’ll use it on our actual routes:

// POST route to mock a login endpoint
router.post("/api/login", validator('login'))

// POST route to mock a forgotten password endpoint
router.post("/api/forgot-password", validator('forgotPassword'))

So now our server listens to post requests on those two routes, and validates the incoming payload.
Now we need to make sure to transform those strings.

Translating the errors

For this, we’ll create another Express middleware which will check all the errors (if any) and convert them into strings in the user’s language.

cd utilities
touch processErrors.js
cd ..

Go ahead and open this new file, where we’ll import another function from express-validator and the npm package object.fromentries.

import { validationResult } from 'express-validator/check'
import fromEntries from 'object.fromentries'

Now, we need to create the function that will do the translation:

const translateMessages = (errObj, req) => {
    // Convert the errObj to an Array
    const errArr = Object.entries(errObj)
    // For each array(err), compare the error msg with the polyglot phrases, and replace it.
    errArr.forEach(err => {
        Object.keys(req.polyglot.phrases).forEach(phrase => {
            if (phrase == err[1].msg) {
                err[1].msg = req.polyglot.t(phrase)
            }
        })
    })

    // Return a function that converts the Array to an Object
    return fromEntries(errArr)
}

In this code, we’re receiving both the error Object created with express-validator (which we’ll extract from the req object with the validationResult function in a bit), and the Express’ req object.

We’re creating an Array from the errObj, and then, for each entry, we’re taking the string we set as the error variable, and comparing it with the keys from the translation messages, changing the string in the errArr (each "err[1].msg") to the actual phrase in polyglot in the desired language (each "phrase").

Finally, we use the imported fromEntries function, to convert the Array back into an Object and return it.

Now, in that same file, we’ll export a middleware function that will be using this translateMessages function to process the errors (if any).

exports.procErr = (req, res, next) => {

    // Verifies if there were validation errors added to the request
    const validationErrors = validationResult(req)

    // If there were errors in the validation
    if (!validationErrors.isEmpty()) {
        // Return the result of the function below
        return res.status(400).send(translateMessages(validationErrors.mapped(), req))
    } else {
        // If no errors, go!
        next()
    }

}

In this code we receive the regular req, res, next from Express, and we first verify if there were any errors using express-validator’s validationResult.
Then, we check if there are errors, and if there are any, we return them with Express’ response.
Check that return closely, as you can see, we send the results of the translateMessages function that is receiving the validationErrors, and the req object.
We also have an else, that when there are no validation errors, calls next() to continue to the next Express middleware.

Sending the errors

So we're able to manage the errors by converting them from the string to their translated version, and packaging it in an object, ready to be sent back to the user if needed.

Now, we just need to use that file!
Let's go back to our auth.routes.js file and make use of this new function by importing it:

import { procErr } from '../utilities/processErrors'

As I mentioned earlier, we built it as an Express Middleware, so we can just add it inside of our chain of events.

And then using it in the actual routes:

// Routes =============================================================
module.exports = router => {

    // POST route to mock a login endpoint
    router.post("/api/login", validator('login'), procErr)

    // POST route to mock a forgotten password endpoint
    router.post("/api/forgot-password", validator('forgotPassword'), procErr)

}

Moving past errors

So now, our code is ready to handle errors in both languages, but what about success messages?

We already have those in the i18n.js file, but we’re not using them.
Lets write the final piece of code:

mkdir controller
cd controller
touch auth.controller.js
cd ..

Open this new file, where we’ll create a couple of exports to handle the final steps of the login and forgot-password processes.
If express didn’t return an error on the last step, theoretically, there are no errors on the user's data, so we’ll go ahead and send success messages here.

Of course, on a real world application we’d go to the database and check the user’s data and confirm it is actually correct and not just valid, but that’s beyond the scope of this tutorial.

So let’s write some code on the auth.controller.js.

exports.login = (req, res) => {

    // If no validation errors, get the req.body objects that were validated and are needed
    const { email, password } = req.body

    // Here, we would make use of that data, validating it against our database, creating a JWT token, etc...

    // Since all the validations passed, we send the loginSuccessful message, which would normally include a JWT or some other form of authorization
    return res.status(200).send({ auth: true, message: req.polyglot.t('loginSuccessful'), token: null })
}

exports.forgotPassword = (req, res) => {

    // If no validation errors, get the req.body objects that were validated and are needed
    const { email } = req.body

    // Here, we would make use of that data, validating it against our database, creating a JWT token, etc...

    // Since all the validations passed, we send the emailSent message
    return res.status(200).send({ auth: true, message: req.polyglot.t('emailSent') })
}

As you can see, both functions are exported to be used in the routes file, and both deconstruct the req.body to get the values we need to use.

I should emphasize that in both cases, further validation would be done in the controller, such as going to the database and checking if the user’s actually exist and are authorized to either login (and their password is correct) or if they’re not banned and are authorized to request a new password.

We’re assuming all of those things happened already, and just sending the response using Express’ res which includes the message with:
req.polyglot.t('key').
This will take the value assigned to that key in the user’s selected language, and return that message.

Now, we need to go back to our routes to add this two functions there.
The final version of auth.routes.js should now look something like this:

import { validator } from '../validator/auth.validator'
import { procErr } from '../utilities/processErrors'
import { login,
    forgotPassword } from '../controller/auth.controller'

// Routes =============================================================
module.exports = router => {

    // POST route to mock a log endpoint
    router.post("/api/login", validator('login'), procErr, login)

    // POST route to mock a forgotten password endpoint
    router.post("/api/forgot-password", validator('forgotPassword'), procErr, forgotPassword)

}

As you can see, we’re importing both login and forgotPassword, and adding them in the post as the final parameter.
These last functions respond with the success messages when everything is ok!

Testing

Let's check that our API is working as expected.

Go ahead and run npm run start. This will build our transpile our code and start the server. If we followed all steps, we should see: App running on port 8080 in our console.

Now open up Postman.

Set the Method to POST
Set the Request URL to localhost:8080/api/login
Set the Headers key to Accept-Language and the value to es_MX
Set the Body to { "email": "test@email.com" }

And click on Send. If all went well, you should see this response:

{
    "password": {
        "location": "body",
        "param": "password",
        "msg": "'password' es un campo requerido."
    }
}

You can play around with the Request URL trying both routes or the Headers setting either en_US or es_MX or another option, also, try and modify the Body to see the different responses from the API.

So that's it!
Now, hopefully you have a clear understanding of how to set up an Express API that responds properly whether your headers are set to es_MX or en_US. Both for error and success messages.

If you have any questions, please go ahead and leave a comment below, or create an issue on the repository, or send me a tweet.
I'm more than glad to help.

Read you soon!

JAMstack and CD pipelines: Create a blog with Nuxt, Netlify CMS and Netlify

Israel Muñoz — Sat, 02 Mar 2019 04:04:01 +0000

This post was originally published on israelmuca.dev

The "old" ways

Say you wanted to create a blog, you could easily run a Wordpress site, with a Linux server distributing your content. On each page load, the server would generate the webpages, and serve them to the user.
Every request puts the server to work.
It's a perfectly viable option, although slower compared to more modern options, more insecure as you have to be doing the updates on your server (or paying more for a managed server), and it requires using PHP and having a database running.

JAMstack to the rescue!

So what is JAMstack? It stands for JavaScript, APIs and Markup. A modern way of writing webpages that are compiled to static assets right before deploying. JavaScript handles the dynamics in your page, what were server-side processes, are now abstracted into APIs if needed, and your markup is compiled during deploys. Go ahead and read all about it on the official webpage.

The benefits that this approach has is that your webpage ends up being blazing fast and with all of your content precompiled, nothing has to be fetched every time the page is served and, you can host it in many many more places (and it's way cheaper (or even free, with Netlify), as it is only HTML and JS files all while getting improved SEO with your page.
Your page is also more secure! Since you don't have exposed APIs, you could even use Wordpress as a CMS but without the security risks or performance problems of running Wordpress itself.
The performance is definitely worth mentioning again, as it is quite easy to make your site super fast.

There is one caveat though. Every time you change anything, you have to rebuild your assets, and deploy them... ugh... but wait!, as that's where a CD pipeline comes into play!

CD pipelines...?

You've probably heard the terms CI/CD being thrown around, with CD sometimes referring to Continuous Delivery or Continuous Deployment. Arguments get quite long when debating about the PRECISE meaning of these words, as you can see in this Stack Overflow question.

In my case, I'm talking about Continuous Deployment, as explained by Netlify here.

Continuous deployment works by connecting a Git repository to a Netlify site and keeping the two in sync.

Easy peasy. We want our repo to be in sync with our site.

But how?

Netlify is an amazing PaaS that has SO MANY FEATURES, really, just to mention a few:

Automated builds and deployments via webhooks straight from your Git repository.
Rollbacks, as previous deployments are not erased.
Continuous Integration tests.
Deployment previews from Pull Requests.
Free SSL certificates.
A CDN.
AND S O, M U C H, M O R E.

Check out their features or dive straight into the documentation pleeeeeaaaase. As everything I mentioned is included in their VERY generous free tier.
So for our use case, we'll be using their automated build and deployment (as I am).

Nuxt.js + Netlify, a match made in heaven

In my case, I've been working with Vue.js and I wanted to build my blog with Vue, so for that, I used Nuxt.js which is a framework built on top of Vue that offers both Server Side Rendering (you need a Nuxt instance running, thus a server as well, a no-go for our project) and also offers Static Site Generator, which compiles all of your fancy Vue code into plain HTML and JS. That's exactly what we need for Netlify! OH YEAH!.

Every time you push your code to the repo, Netlify pulls the latest version, and in my case, runs nuxt generate and then uploads the /dist folder into their CDN. And that's it! Your latest version is live in a minute or two. No need to upload anything manually or check what version is uploaded... Everything is automated now... Continuous Deployment FTW!

Netlify CMS

Last but not least. How can you manage your content like this?
Remember that the JAMstack best practices mention that ideally, everything lives on your git, so anyone can, with a couple of clicks, get going and contribute to your project.

That's where Netlify's CMS comes in. It's an Open Source Software, that helps you use your Github as a 'database' in a sense. Allowing you to create blog posts directly into .md files, which you can push into the repo to trigger the builds, creating new blog posts just like that.
They have an easy to use interface, and even have an editorial workflow, that set articles to be deployed as Pull Requests on your Github, allowing you or your team to review them (using Netlify) before merging them.

All in all, these are amazing tools that let us create blazing fast sites, in a modern environment and require very little configuration for such an amazing final product.

Getting started

For this, we'll only be needing:

Github account
Netlify account
Vue/Nuxt understanding

Fork the repo

Using your Github account, go ahead and click here to fork the repo or just clone it.

Build Setup

Install all the dependencies

npm i

Now, you can run the code in development with:

npm run dev

This will serve your page in localhost:3000 with hot reload.

Once you're ready to generate your static assets for production:

npm run generate

This will create a /dist folder with the assets. This folder is not committed.
This is what Netlify will be building on their server, and then uploading the results to their CDN. We don't need to do this manually ever. We just do it for the sake of watching what happens inside Netlify.

Configure your new repo

Netlify CMS

You'll need to define your fields and files for your content. I'm using defaults very similar to what you can see in here, dev.to. Mostly covering the title, description, and keywords for SEO purposes, also a little summary of the post as well as the main image which is used both in the ArticleCard.vue and the Header.vue in the blog post page.

You can configure these fields in: static/admin/config.yml, and feel free to check the Netlify CMS Documentation for extra customization.

While your local server is running, you can access localhost:3000/admin/ to modify the content of your blog. You can also do it once it's deployed when you have the Netlify's address that's given to you.

Routes

In here, both Nuxt and Nuxtdown work together to create the routes in the website.

In the pages directory, you'll find an index.vue which is, as the name implies, the index of our site.
This is handled by Nuxt.

The pages/blog/ directory will work as a directory in our site as well (israelmuca.dev/blog/... in my case), which will hold all the blog posts that are created using the _blogpost.vue template inside. It will be compiled once for each .md in the content/blog/ directory. You can see how the content is fetched inside of that .vue file.
This is handled by Nuxtdown.

You can configure Nuxtdown in: nuxtdown.config.js, and please go ahead and check the Nuxtdown Documentation to further understand what is happening or to change the functionality.

The rest of the site

The rest of the site is a regular Vue + Nuxt app, I tried to comment the code where I think it's needed the most, and you can configure Nuxt in: nuxt.config.js, also, as usual, please check the Vue.js and Nuxt.js documentation to further understand this code if you have any questions.

Congratulations

By this point, you should have a fully functional Nuxt generated, Netlify hosted, blog site.

Issues

If you have any problems implementing this, please don't hesitate and create a Github Issue or send me a tweet.

Thanks

There's a phrase that I love and always try and remember:

If I have seen further it is by standing in the shoulders of Giants
Isaac Newton

Being true to that phrase, I have to acknowledge the many people that in one way or another contributed to this specific repo:

Thanks again, and read ya'll soon!

Hi! I'm Israel, and I'll introduce you to my corner of the web

Israel Muñoz — Fri, 01 Mar 2019 17:46:24 +0000

This post was originally published on israelmuca.dev

Who am I?

My name is Israel, born and raised in Monterrey, México, currently, more and more Chicago based. I studied Engineering in Software Development back in 2007, worked as an intern for a couple of years, before focusing mostly on my own IT Business for over 10 years!

Why a blog?

Why not...?

Jk, I'm not sure really, I guess it all started when I began reading this site. I realized that writing for the sake of writing is ok, and if I can help anyone out with what I'm writing, even better.
Afterward, I read Sara Soueidan's Just Write article and I felt that I should definitely create my own blog.
Also, I love googling about a new technology stack or library and finding amazing how-tos, guides, and tutorials online, which I invariably read, regardless if I'll actually use the library, so I guess I decided to also pay back some of that amazing content with some made by myself.

What will I be writing about?

Mostly, WebDev stuff. I've had different roles through the years, mostly Project Management and Business Analyst but since late 2017 I've gotten back into writing code myself, focusing on both backend and frontend.
I've also worked on Education, and my current startup is helping Mexican schools get up-to-date with their Computer Science curriculum, so some stuff about schools as well.
And last but not least, entrepreneurship. I've been involved in a number of startups throughout the years. Some have flunked badly, some are alive and well, so I guess I have some insight into that as well.

Why is 42 the answer to life... the universe... everything?

Regardless of what many people claim, Douglas Adams once claimed in a quite nonchalant way in an interview:

"The answer to this is very simple," Adams said. "It was a joke. It had to be a number, an ordinary, smallish number, and I chose that one. Binary representations, base 13, Tibetan monks are all complete nonsense. I sat on my desk, stared into the garden and thought 42 will do. I typed it out. End of story."

So much for all the crazy hypothesis.

Closure

So there's that! My first few articles will all be WebDev related, with the first one being a little something about the JAMstack, Netlify, and Nuxt.js, which are the backbone of this blog.

So thanks for reading and see you soon!