Rapid Internationalization of Shiny Apps: shiny.i18n Version 0.2

Estimated time:

time

min

<h2>Rapid Multi-Language Support for Shiny Apps</h2> Have you ever created a multilingual Shiny application? Chances are the answer is yes. Especially if you are a big fan of <a href="https://appsilon.com/shiny" target="_blank" rel="noopener noreferrer">Appsilon</a>'s blog and have read our <a class="editor-rtfLink" href="https://wordpress.appsilon.com/internationalization-of-shiny-apps-i18n/" target="_blank" rel="noopener noreferrer">first article</a> on the topic. If that's not the case - fear not - we'll cover everything you need to know today about how to rapidly add multi-language support to Shiny apps. If you already know a lot about <code class="language-r">shiny.i18n</code>, feel free to jump to any section: <ul><li><a href="#introduction">Introduction to shiny.i18n</a></li><li><a href="#whats-new">What's New in Version 0.2.0</a></li><li><a href="#example">Shiny Dashboard Example</a></li><li><a href="#conclusion">Conclusion</a></li><li><a href="#learn-more">Learn More</a></li></ul> To learn more about Appsilon's open-source packages, see our new <a href="http://shiny.tools" target="_blank" rel="noopener noreferrer">Open Source Landing Page:</a> <a href="http://shiny.tools"><img class="size-large wp-image-5332" src="https://wordpress.appsilon.com/wp-content/uploads/2020/09/Screen-Shot-2020-09-23-at-5.02.14-PM-1024x504.png" alt="Appsilon's shiny.tools landing page for our open source packages." width="1024" height="504" /></a> Appsilon's shiny.tools landing page for our open source packages. <h2 id="introduction">Introduction to shiny.i18n</h2> At Appsilon we routinely build <a href="http://demo.appsilon.ai" target="_blank" rel="noopener noreferrer">Shiny applications</a> for Global 2000 companies, and we've come across the internationalization problem multiple times. It made sense to develop an open-source package that handles multilanguage options with ease. Version 0.1.0 has been out for quite some time now, and we are proud to announce a new, upgraded version - 0.2.0. <blockquote>NOTE: shiny.i18n usage is not limited to Shiny apps. You can use it as a standalone R package for generating multilingual reports or visualizations without Shiny. We decided on the name "shiny.i18n" because Shiny is the most common and obvious use-case scenario for the package.</blockquote> The latest version of the package is available on <a class="editor-rtfLink" href="https://cran.r-project.org/web/packages/shiny.i18n/index.html" target="_blank" rel="noopener noreferrer">CRAN</a>, so installation is extremely easy: <pre><code class="language-r">install.packages('shiny.i18n')</code></pre> The package utilizes specific translation file data formats - currently in JSON and CSV. <h3>JSON Format</h3> Here's an example of a JSON translation file for English, Polish, and Croatian languages: <pre><code class="language-r">{ "languages": ["en", "pl", "hr"], "translation": [ { "en": "MtCars Dataset Explorer", "pl": "Eksplorator danych: MtCars", "hr": "Istraživanje MtCars Dataseta" }, { "en": "Change language", "pl": "Wybierz język", "hr": "Promijeni jezik" }, { "en": "Select", "pl": "Wybierz", "hr": "Odaberi" }, { "en": "This is description of the plot.", "pl": "To jest opis obrazka.", "hr": "Ovo je opis grafikona." }, { "en": "Scatter plot", "pl": "Wykres punktowy", "hr": "Dijagram raspršenja" }, { "en": "X-Axis", "pl": "Oś X", "hr": "X os" }, { "en": "Y-Axis", "pl": "Oś Y", "hr": "Y os" } ] }</code></pre> As you can see, only two fields are required: <ul><li>languages - list of language codes</li><li>translation - JSON objects containing translation to all languages</li></ul> <h3>CSV Format</h3> The main idea behind this format is to support distributed translation tasks among many translators. It's not convenient for them to work together on a single file, but instead, they can store individual files in the same folder. Here's the example folder structure: <pre><code class="language-r">translations/ translation_pl.csv translation_hr.csv</code></pre> Every CSV file in the translations folder should look like this: <pre><code class="language-r">en, hr Hello Shiny!, Pozdrav, Shiny! Histogram of x, Histogram od x This is a description of the plot., Ovo je opis grafikona. Frequency, Frekvencija Number of bins:, Broj binova: Change language, Promijeni jezik</code></pre> Awesome! Let's now take a look at the version 0.2.0 changelog, and then we'll jump to a dashboard example. <h2 id="whats-new">What New in Version 0.2.0</h2> The complete changelog list for every version is located at <a class="editor-rtfLink" href="https://github.com/Appsilon/shiny.i18n/blob/master/CHANGELOG.md" target="_blank" rel="noopener noreferrer">GitHub.com</a>, but here's what new in the most recent version: Added: <ul><li>Auxiliary preprocessing functions - they create example translation CSV or JSON files</li><li>RStudio add-in that searches for all i18n tags</li><li>Browser-side translations to dramatically improve performance</li><li>automatic translations via API (currently only google cloud supported)</li><li>2 vignettes with tutorials</li><li>examples with live language translation on the UI side and with automatic translation via API</li><li><code class="language-r">pkgdown</code> documentation</li></ul> Changed: <ul><li><code class="language-r">translate</code> method now automatically detects whether the object is in UI or server and applies reactive or js translation accordingly</li></ul> <h2 id="example">Dashboard Example</h2> To demonstrate how <code class="language-r">shiny.i18n</code> works in practice, we'll develop a simple dashboard application based on the <code class="language-r">mtcars</code> dataset. This dashboard can be used to make scatter plots of the two columns specified by the user. To start, we'll import a couple of required libraries and initialize the translator. We've stored the translations file in <code class="language-r">translations/translation.json</code>, so keep that in mind if yours is stored elsewhere: <pre><code class="language-r">library(shiny) library(shiny.i18n) library(ggplot2) i18n <- Translator$new(translation_json_path='translations/translation.json') i18n$set_translation_language('en')</code></pre> Next, we can define the UI. There are a couple of things we want to have: <ul><li>Dropdown menu for language - somewhere in the top right is fine</li><li>Title panel - to inform the user what our app is all about</li><li>Sidebar - contains two dropdown menu for X and Y axes, respectively</li><li>Main panel - contains a chart and the chart description</li></ul> Here's the code for the UI: <pre><code class="language-r">ui <- fluidPage( shiny.i18n::usei18n(i18n), tags$div( style='float: right;', selectInput( inputId='selected_language', label=i18n$t('Change language'), choices = i18n$get_languages(), selected = i18n$get_key_translation() ) ), titlePanel(i18n$t('MtCars Dataset Explorer'), windowTitle=NULL), sidebarLayout( sidebarPanel( width=3, tags$h4(i18n$t('Select')), varSelectInput( inputId='x_select', label=i18n$t('X-Axis'), data=mtcars ), varSelectInput( inputId='y_select', label=i18n$t('Y-Axis'), data=mtcars ) ), mainPanel( plotOutput(outputId='scatter'), tags$p(i18n$t('This is description of the plot.')) ) ) )</code></pre> The last step remaining is to build the server. The <code class="language-r">observeEvent</code> function will help us to detect language change and to make translations accordingly. As a final step, we can use the <code class="language-r">renderPlot</code> reactive function to display our scatter plot: <pre><code class="language-r">server <- function(input, output, session) { observeEvent(input$selected_language, { update_lang(session, input$selected_language) }) output$scatter <- renderPlot({ col1 <- sym(input$x_select) col2 <- sym(input$y_select) ggplot(mtcars, aes(x= !! col1, y= !! col2)) + geom_point(size=6) + ggtitle(i18n$t('Scatter plot')) }) } shinyApp(ui=ui, server=server)</code></pre> And that's all we have to do. Our final application is simple but perfectly captures how easy it is to implement multilanguage functionality. <img class="aligncenter wp-image-5740 size-full" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b021d3a20f7e6672b82c7e_FinalApp.gif" alt="" width="1252" height="574" /> <h2 id="conclusion">Conclusion</h2> In this relatively short hands-on guide, we've demonstrated what <code class="language-r">shiny.i18n</code> is and how it can be used to develop multilingual dashboards. Version 0.2 brought some exciting new features. The most important feature to us is the ability to not have to render everything in the <code class="language-r">server</code> function, which was the case with the earlier version. The other new feature is automatic translation, powered by Google Cloud. It requires a bit of setup, and you can learn more about it <a class="editor-rtfLink" href="https://github.com/ropensci/googleLanguageR/" target="_blank" rel="noopener noreferrer">here</a>. <blockquote>Curious about automatic translation? <a class="editor-rtfLink" href="https://github.com/Appsilon/shiny.i18n/blob/master/examples/automatic_translations/app.R" target="_blank" rel="noopener noreferrer">Here's how to implement it with Shiny and i18n.</a></blockquote>  <h2 id="learn-more">Learn More</h2><ul><li><a href="https://appsilon.com/shiny-worker-package/" target="_blank" rel="noopener noreferrer">shiny.worker: Speed Up Shiny Apps by Offloading Heavy Calculations</a></li><li><a href="https://appsilon.com/how-to-scale-a-shiny-dashboard/" target="_blank" rel="noopener noreferrer">Video: How to Scale Shiny Dashboards</a></li><li>Appsilon is hiring talented R Shiny Developers. Check out our open positions <a href="https://appsilon.com/careers/" target="_blank" rel="noopener noreferrer">here</a>.</li></ul>