npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

iris-i18n

v0.1.25

Published

IRIS - Site Localisation Module

Downloads

24

Readme

iris-i18n

IRIS - Site Localisation Module

iris-i18n module is integrated within iris applications and provides tools for web site translation. This module does not currently integrate with Transifex or any other translation services. It provides it's own translation backend, which function in real-time - any entry translated is immediately visible on the web site.

iris-i18n requires EJS rendering engine.

Configuration

your-app/config/ folder contains 3 files:

  • i18n.conf - configration settings
  • i18n.users - configuration for user accounts
  • i18n.data - data file containing all translation entries

i18n.conf

i18n.conf mainly contains list of supported languages and is automatically saved each time options are changed in the translation backend (enabling/disabling active languages).

i18n.users

i18n.users should be created locally when your application is deployed. It must not be present in git (unless your project is a private repository)

User configuration is done as follows:

{
	"<username>" : {
		"locales" : "en fr",	// or "*" for all  (controls access to specific languages, space separated locale codes)
		"pass" : "<sha256>"		// hex sha256 of pass
	}
}

User login to the i18n backend uses geometric back-off algorithm, which means that each time incorrect login is made from a specific IP, the amount of seconds user has to wait doubles.

To generate a password, you can use simple hex output of sha256. This can be easily done here: http://www.xorbin.com/tools/sha256-hash-calculator or in NodeJs: console.log(require("crypto").createHash("sha256").update("<password>").digest("hex"))

i18n.data

i18n.data is a custom data format that is kept in git and lives together with your project. The file format is custom in order to allow easier merging when encountering git merge conflicts.

Translation Entries

Translation entries are generated using two phases. During the first phase, iris-i18n module scans html and ejs files located in your project and extracts all visible entries. Second phase is when translation entries are actually displayed on the web site.

All translation entries are kept in memory and when entries are translated, the database is delay-flushed to i18n.data file.

To check if any translation has been done, you can simply do git diff in your project to see if any modifications have been done to i18n.data file.

Usage

iris-i18n provides a variable _T globally available within the EJS rendering context. _T is a function and a variable container (object) at the same time. Following fields are available under _T:

  • _T.locale - current locale code
  • _T.languages - list of active/enabled languages
  • _T.availableLanguages - list of available languages (including languages that have not been activated/enabled)
  • _T.source - source language of the site (typically "en")

To add a text entry to the translation database, user must pass it through a _T() function during EJS rendering phase (by embedding it into EJS view) as follows:

<!-- without support for HTML entities -->
<%= _T("Hello World") %>

<!-- with suppor for HTML entities -->
<%- _T("Hello World") %>

NOTE: Using EJS escaping for HTML entities <%= %> tag is recommended as non-escaping output tag <%- %> allows HTML injection into the web page. However, in some cases, especially when it comes to RTL languages and text envelopping links, it is desirable to re-position text around the link. In this case, unescaped text is fine. Just make sure to review translated entries or make sure you trust people who are translating your content.

For security sensitive sites and applications, you can deploy your NodeJs server in an alternate location (or on an alternate port), have people do the translation and then validate it by reviewing i18n.data file. Once done, commit the changes and pull them on the primary server.

Note on escaping - when allowing for unescaped HTML entities, you must make sure that HTML entities in the original HTML are preserved, as otherwise this may break your HTML content. (i.e. <a href="abc"> is preserved in original form - ommission of quotes will produce HTML with invalid syntax)

IMPORTANT: When pulling i18n.data changes from git, you must restart your process, preferably stop, pull and start. If site content is actively being translated, there is a risk of the running process to overwrite i18n.data file if someone translates an entry after the updated file has been pulled. We may change this behavior in the future.

If you have text located in client-side JS objects, best way to handle this is to relocate these objects into the EJS space, transform them via the _T() function and re-publish them back to client JS objects. Example:

<% 
	var obj = [
		{ title : "first" },
		{ title : "second"}
	];

	_.each(obj, function(o) {
		o.title = _T(o.title);
	})
%>

<script>
	var obj = <%= JSON.stringify(obj) %>
</script>

Translation backend

Translation backend can be accessed via /i18n/ path in your iris application. (for example: http://your-site.com/i18n/)

Description of the user interface is available here: https://github.com/aspectron/iris-i18n/blob/master/doc/iris-i18n-user-interface.pdf