Getting text strings from Flare into a JSON file

This forum is for Single-Sourcing your Flare content to multiple outputs.
Post Reply
JeromeR
Propeller Head
Posts: 64
Joined: Fri Mar 20, 2009 2:15 pm
Contact:

Getting text strings from Flare into a JSON file

Post by JeromeR »

Hi,

I have a client, in the financial services sector, working on a web-application. The web-application's GUI (user interface) is full of text, as you can imagine. They want to translate to 4 languages. The text strings are in a JSON file, one for each language.

• Is there a way to keep text strings in Flare (ideally as variables), with output going to a marked up JSON file?
• Or should I ask the Dev team to write code to convert the Flare variables file into marked-up JSON?
• Or is there another solution you know of…?

The benefits to me of using Flare is that I could manage the translation and reviewer feedback with Lingo.

Thanks in advance for your ideas.
Last edited by JeromeR on Wed Nov 09, 2016 9:35 am, edited 1 time in total.
JeromeR
Propeller Head
Posts: 64
Joined: Fri Mar 20, 2009 2:15 pm
Contact:

Re: Getting text strings from Flare into a JSON file

Post by JeromeR »

An update: we solved this by getting developers to write a transformation script and validation scripts, and a dev-ops to implement various Jenkins pipeline jobs.

Goals for the content: Speedy changes, managed

One goal was to manage—by using Flare—all text that appears in the UI of a web application. It's an Agile, continuous delivery situation, so the building and publication needed to be largely automated. As for managing "all text," that really meant ALL text: the marketing- and persuasive content, the embedded assistance such as instructions, the labels for controls (check boxes, radio buttons, text boxes, drop-down lists, etc), the content in or with the controls (such as the choices in a drop-down list or the text of a check box), the tool tips, the feedback such as confirmations, error messages, etc. So all text managed in Flare: that was one goal.

The web-app is in the financial services sector, and it changes constantly as the client tweaks the web-app to improve its conversion rate. Continuous delivery—the ability to deploy text changes speedily without a service outage—was another goal.

Here's the high-level solution we adopted
  1. As content requirements arrive, add new text to a MadCap Flare project¹ or modify existing text in a Flare project¹.
    • If it's new text, wrap each "unit" of text in a <div></div> that has a unique identifier by using a custom attribute (so using the data- prefix in order to be HTML5 compliant.)
    • The text gets marked up, if needed—especially with semantic tags that help the content make sense machines. By agreement, only certain HTML block- and inline markup is permitted in the <div></div> element, such as <h1>, <p>, <strong>, <ul>, <ol>, and so on. The markup gets validated² later.
    • We also add microformat markup, where relevant, to help some content make sense to machines.
    • If needed, we get the content reviewed (and approved) by the stakeholders, using MadCap Contributor³.
    • Images and video were excluded from scope for this project. I'm currently working on another project for the same client where media is in scope.
    • We re-use content where possible by using such Flare features as variables and snippets.
  2. In Flare, push the content to source control, and then communicate any new unique identifiers to the Development team, so they can use that to make the application call the text, when needed.
    • For source control and version control, we used Git (and Stash).
    • Git integrates nicely with Flare; with multiple technical communicators in the same project, we never had one overwrite the changes made by another, and Flare informed us of collisions.
    This is the end of the technical communicator's work (unless errors occur), although the technical communicator may choose to take a look at the output on the integration server, mentioned later.
  3. Jenkins—the thing that we named The Content Pipeline for Continuous Delivery—continually listens for changes in source control, and when it detects a change, it automatically triggers a series of Jenkins jobs. These jobs:
    1. Validate² Flare's HTML source files.
    2. Trigger validation² scripts.
    3. Trigger a MadCap MadBuild automated (silent) Flare build² of the output. In this case the output was HTML5. I'm currently doing this again, on another project for the same client, where the output will be DITA. (Note that the Flare installation for this step requires its own Flare license.)
    4. Trigger a transformation script² on the output. In this case it was transformed to JSON. In the current case this will be various output formats.
    5. Trigger validation² scripts on the transformed output.
    6. Upload² the result to a server for integration testing.
    During any of the above Jenkins jobs, if a step or a validation fails, Jenkins stops the job and notifies the technical communicator with details (in a "console" log), so that the error can be fixed in Flare.
  4. Any team-member can run the web-application on the system integration test (SIT) server to see the new or modified text in the web-app's UI, or user interface.
    • We actually have a series of servers, for various types of testing, and a Jenkins job moves the content from one to the next, as the content passes each set of tests and inspections. Those jobs are not triggered by the technical communicator, but by the various test teams.
  5. The internal client—called "the business"—triggers a Jenkins job that publishes the content to Production (live), where customers can see it.
    • Not all users have permission to this step, which is part of the governance ("Compliance") requirements.
    • The business also does a "sanity check" on the live site, to inspect the change.
    • This publication occurs without a service outage. However, there's another Jenkins pipeline that publishes code changes and text changes, and that does require an outage. That is not a continuous delivery process, as it takes days to schedule and prepare.

¹ Each language has its own Flare project. We set up MadCap Lingo to help with the translation work between Flare projects.

² The validation is essential in a continuous-delivery pipeline, because the content that the Technical Communicator pushes could be out of sync with the current release of the web-application's code, and because since incorrect markup can break the web-application. Validation consists not only of custom scripts written by the developers, but also warnings and errors generated by Flare itself when the output is generated, from the transformation process, and from upload errors.

³ We set up Contributor to get content signed off by stakeholders—such as the marketing- and legal teams—and their feedback ends up in source control as a permanent audit trail of the who, when, and what (which iteration) of content approval. This is part of the governance ("Compliance") requirements.

:)
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Getting text strings from Flare into a JSON file

Post by Psider »

Thanks for that detailed post. It's always interesting hearing about what other people are doing (wish I could see it in action. :) )
danidelcar
Jr. Propeller Head
Posts: 8
Joined: Fri Dec 02, 2016 4:30 am

Re: Getting text strings from Flare into a JSON file

Post by danidelcar »

Hi JeromeR,

Did you encounter working with Jenkins any issue if you had any warning or ignored warning when building in Flare?, if so, do you have any recommendation on how to solve it?

Thanks!

Dani
Post Reply