Jargon SDK for Amazon Alexa (nodejs)
The Jargon SDK makes it easy for skill developers to manage their runtime content, and to support multiple languages from within their skill.
Need help localizing your skills to new languages and locales? Contact Jargon at firstname.lastname@example.org.
This version of the SDK works with Amazon Alexa skills that are built using the ASK SDK v2 for Node.js.
Like the ASK SDK, the Jargon SDK is built using TypeScript, and includes typing information in the distribution package.
Content resources and resource files
Content resources define the text that your skill outputs to users, via Alexa's voice, card content, or screen content. It's important that these resources live outside of your skill's source code to make it possible to localize them into other languages.
The Jargon SDK expects resource files to live in the "resources" subdirectory within your lambda code (i.e., skill_root/lambda/custom/resources). Each locale has a single resouce file, named for that locale (e.g., "en-US.json").
Resource files are JSON, with a single top-level object (similar to package.json). The keys within that object are the identifiers you'll use to refer to specific resources within your source code. Nested objects are supported to help you organize your resources.
Resource value format
Resource values are in ICU MessageFormat. This format supports constructing text at runtime based on parameters passed in from your code, and selecting alternative forms to handle things like pluralization and gender.
It's important for Alexa skills to vary the words they use in response to users, lest they sound robotic. The Jargon SDK makes ths simple with built-in variation support. Variations are defined using nested objects:
When rendering the key
resourceWithVariations the Jargon SDK will choose a variation at random (with other more complex
methods coming in future versions). If you render the same resource multiple times within a single request (e.g., for spoken
content and for card or screen content) the SDK will by default consistently choose the same variation.
Note that you can always select a specific variation using its fully-qualified key (e.g.,
You can determine which variation the SDK chose via the ResourceManager's selectedVariation(s) routines.
The core class you'll work with. JargonResponseBuilder mirrors the ASK SDK response builder, but changes string parameters containing content presented to users to RenderItems.
A RenderItem specifies a resource key, optional parameters, and options to control details of the rendering (which are themselves optional).
RenderParams are a map from parameter name to a string, number, or
The use of a
RenderItem instance as a parameter value makes it easy to compose multiple
resource together at runtime. This is useful when a parameter value varies across locales,
or when you want the SDK to select across multiple variations for a parameter value, and reduces
the need to chain together multiple calls into the
ri helper function simplifies constructing a
RenderOptions allows fine-grained control of rendering behavior for a specific call, overriding
the configuration set at the
JargonSkillBuilder wraps the ASK skill builder, and handles all details of intializing the Jargon SDK,
installing request and response interceptors, and so on.
const skillBuilder =
JargonResponseBuilder uses a
ResourceManager to render strings and objects. You
can directly access the resource manager if desired, for use cases such as:
- obtaining locale-specific values that are used as parameters for later rendering operations
- incrementally or conditionally constructing complex content
- response directives that internally have locale-specific content (such as an upsell directive)
- batch rendering of multiple resources
- determining which variation the ResourceManager chose
Note that the render routines return
Promises to the rendered content, not the content directly.
ResourceManager is part of the package @jargon/sdk-core,
and can be used directly from code that isn't based on ASKv2.
Adding to an existing skill
First add the Jargon SDK as a dependency of your lambda code (skill_root/lambda/custom)
- npm i --save @jargon/alexa-skill-sdk
- yarn add @jargon/alexa-skill-sdk
Next, wrap the Alexa skill builder with Jargon's skill builder:
// Import the Jargon SDKconst Jargon =// Wrap the skill builderconst skillBuilder =
The content that your skill outputs via speak(), reprompt(), etc., needs to move from wherever it currently lives in to Jargon resource files. That's currently a manual step, but in the future we'll have tools to help automate portions of the process.
Resource files go under skill_root/lambda/custom/resources, and are named by the locale they contain content for (e.g., "en-US.json").
Switch over to the Jargon response builder
In your skill handlers access the Jargon reponse builder via one of the following methods:
TypeScript users: you'll need to cast
JargonHandlerInput if you want to use one of
the first two forms.
Setting up a new skill
We'll soon have templates in place for use with the ASK CLI for bootstrapping new skills with the Jargon SDK pre-installed, along with skeletons for resource files.