This content originally appeared on Level Up Coding - Medium and was authored by Lee James Gilmore
Serverless AppSync localisation and i18n ?
Introduction
Since AWS brought out AppSync it has been a game changer in the Serverless World, allowing teams to use a managed GraphQL service, for both web applications and mobile. If you couple this with the Serverless Framework and the serverless-appsync plugin, you have a very powerful way to quickly build serverless production ready GraphQL APIs. ?
One of the downsides however is the use of VTL (Velocity Template Language) templates, i.e. the ‘glue code’ between the graphQL resolver and the underlying service (DynamoDB, Lambda, HTTP etc), is that they are not very flexible when it comes to localisation, reusing regexes, static data and i18n! ?
This blog post will discuss a novel way to translate the backend AppSync logs, config values and the API return values based on the locale it is built for! You can find the very basic example repo here.
Quick reminder, what is AppSync and GraphQL?
AWS AppSync is described as:
AWS AppSync is a fully managed service that makes it easy to develop GraphQL APIs by handling the heavy lifting of securely connecting to data sources like AWS DynamoDB, Lambda, and more. Adding caches to improve performance, subscriptions to support real-time updates, and client-side data stores that keep off-line clients in sync are just as easy. Once deployed, AWS AppSync automatically scales your GraphQL API execution engine up and down to meet API request volumes. — AWS
This video gives a great overview of the service:
So what is the approach to localisation? ?
Let’s take an example to work with — the code of which can be found here.
You have built a cool notes service for your company which has been a massive success in the UK, and now product management would like the service deployed to France for their French customers! The issue we have however is:
- The return values from the GraphQL resolvers are all in English (hardcoded in the VTL), and they need to be in French! ??
- The team which will support the product when deployed to the Paris region all read and speak French, so ideally the logs would be in French also (again, hardcoded in the VTL). ??
- We don’t want to duplicate all of that effort or to jump out to lambda each time another locale wants to take on the service, when we don’t need a compute layer! ?
This is a fictitious example of course lol, and my french is non-existent, although I have used this approach on enterprise serverless domain services which were built out at a previous company using AppSync, and utilised across multiple locales on AWS. This was a “build once and deploy to any locale” first mindset across the full stack.
The approach is to use the substitutions property at serverless build time to inject the correct values into the VTL template based on the locale flag and JavaScript. This is utilising the serverless.js or serverless.ts files discussed in this further blog I wrote here ✔️
Let’s see an example!
First of all we need to create some JavaScript files which can be imported into the serverless file and the return of the functions spread into the JS substitutions property used for translations, for example for the error messages:
and error types:
Note that within the invalidValueErrorMessage property we have a placeholder of {0} which corresponds to the following VTL code:
We can then spread the values into the substitutions property into the serverless.js file so they will replace any placeholders at serverless build time:
substitutions allows to pass variables from here to velocity templates
${exampleVar1} will be replaced with given value in all mapping templates — https://github.com/sid88in/serverless-appsync-plugin
This means that if we now try to use the resolvers getNote or saveNote with a noteId of 0 when deployed to the Paris region you would get the following locale specific error message/logs:
or the following for the UK deployment:
What other cool things can you do?
This flexible approach also allows us to return hardcoded data such as enums and basic lists using a local resolver rather than going to a datastore like DynamoDB. An example VTL would look like the following for the resolver getNoteTypes:
with the corresponding JavaScript function getNoteTypes.js being:
Which will return the following values in the UK when queried:
and the following for the French deployment:
This approach I have used in the past to also pass through common regexes which can be utilised in the VTL files using the $matches method, but also in Lambdas and other code so they are defined in one place. You can also do the same for config values, for example max page sizes in an ElasticSearch pagination request VTL. The key here is to export them into an NPM package or have them as part of your monorepo so they can be utilised across your full stack.
The important takeaway is showing the flexibility of JavaScript/TypeScript over other languages such as Java, Python and Dotnet Core etc when working with Serverless.
I hope you have found that useful and please let me know on LinkedIn if you did!
AppSync Wish List
If I had a specific wish list for the AppSync team it would be:
- Giving the option for internal APIs like you get with API Gateway. Many teams would like to use AppSync for internal corporate applications but there is no way to make this accessible only to a given network (or VPN) that I am aware of ?
- This ❤️ → https://github.com/aws/aws-appsync-community/issues/147
- Allowing for no authentication if required. Yes you can get around this with IAM but for many sites that don’t require being logged in this is a pain to setup..
Wrapping up
If you found this article interesting then lets connect on any of the following:
https://www.linkedin.com/in/lee-james-gilmore/
https://twitter.com/LeeJamesGilmore
If you found the articles inspiring or useful please feel free to support me with a virtual coffee https://www.buymeacoffee.com/leegilmore and either way lets connect and chat! ☕️
If you enjoyed the posts please follow my profile Lee James Gilmore for further posts/series, and don’t forget to connect and say Hi ?
About me
“Hi, I’m Lee, an AWS certified technical architect and Lead Software Engineer based in the UK, currently working as a Technical Cloud Architect and Principal Serverless Developer, having worked primarily in full-stack JavaScript on AWS for the past 5 years.
I consider myself a serverless evangelist with a love of all things AWS, innovation, software architecture and technology.”
** The information provided are my own personal views and I accept no responsibility on the use of the information. ***
Serverless AppSync Localisation & i18n ? was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Lee James Gilmore
Lee James Gilmore | Sciencx (2021-07-15T17:38:37+00:00) Serverless AppSync Localisation & i18n. Retrieved from https://www.scien.cx/2021/07/15/serverless-appsync-localisation-i18n/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.