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

@mr_timur_m/localeapp

v1.7.1

Published

LocaleApp manager

Downloads

6

Readme

localeapp

Build Status

This package provides some powerful features to manage your translation files and sync them with Localeapp. If your project uses Localeapp to manage locales translation remotely then this tool might come useful.

Description

When working with locales through Localeapp, the files containing translation keys can become extremely large and complex to be easily managed. This tool tries to bring more organization within locales in a project by using folders to separate keys and compile them into a single file that can easily be synchronized with Localeapp.

Features

  • Compile translation keys from a folder structure source to a single .yml file.
  • Synchronise with your Localeapp project
  • Update the source files in the folders when pulling from Localeapp.

Installation

This package is most useful when installed globally, as CLI commands can just be ran through localeapp [cmd], however it can be installed locally by project if necessary. Install localeapp locally if you already have node dependencies in your project:

$ npm install @rimiti/localeapp

or

$ yarn add @rimiti/localeapp

If you don't have node dependencies but still wish to use this package you can install it globally through

$ npm install -g @rimiti/localeapp

or

$ yarn global add @rimiti/localeapp

How to use it?

Setup

To start using localeapp there is a minimal set up that needs to be taken care of first.

Create a .localeapprc file where all the paths and locale information for the localeapp commands is specified. A normal usage set up file looks like this:

If you want to use simple path definition

{
  "target": "locales",
  "source": "locales",
  "default": "en"
}

It will generate the bellow folder structure:

src
│
├── locales/
│   ├── en.yml
│   ├── fr.yml
│   ├── pt.yml
│   ├── es.yml
│   └── index.js
│

If you want to create dynamic paths

{
  "target": "locales/{{locale}}",
  "source": "locales/{{locale}}",
  "default": "en"
}

The {{locale}} (or {{ locale }}) variable is automatically replaced by the locale. This option can be really useful if you need to create paths with the bellow structure:

src
│
├── locales/
│   ├── en/
│   │   └── en.yml
│   ├── fr/
│   │   └── fr.yml
│   ├── pt/
│   │   └── pt.yml
│   ├── es/
│   │   └── es.yml
│   └── index.js
│

Where target is the path to the folder where your compiled translation keys file will be written, source is the root of your folder structure and default is the default language of your locales. target is also where all the locale files will be written to when pulling from Localeapp. In this example all local translation keys are in English, and the generated file (in /locales) is en.yml. It is this file that is then synchronised with Localeapp. The default locale should match the one in your remote Localeapp project.

To enable syncinc between localeapp and the local files (with push and pull) you have to first initialise localeapp with the localeapp project key with:

If you want to use environment variable (recommended)

$ export LOCALEAPP_KEY=<your Localeapp key>
$ yarn localeapp init

If you want to pass your key as cli argument (not recommended)

$ yarn localeapp init <your Localeapp key> 

The key can be found in Settings/API Key in Localeapp. This file is not commited to it will stay secret in your local environment. The key will be used to synchronise your files with the remote project.

Commands

There are 3 commands available:

  • UPDATE: Takes the contents of the source files and compiles them into the single translation keys file, the default locale.
  • PUSH: Runs UPDATE and then synchronises the local compiled translation with your remote Localeapp project. If your default locale is en it will compile everything to en.yml and push it to the project.
  • PULL: Will fetch all the translations from Localeapp and update/create the individual locale files (e.g. en.yml and fr.yml if you have English and French translations). Then it will update your source files with any changes that might have been made on the remote project in the default locale.

If you installed the package globally you have access to the CLI everywhere, thus you can run:

$ localeapp <cmd>

directly within the root folder of your project. Thus for the above commands you would have:

$ localeapp update
$ localeapp push
$ localeapp pull

Were you to install localeapp locally you will need to call npx localeapp update or better, yarn localeapp update.

NOTE: when using options like the ones described below, you will need to include the -- parameter to ensure the options are passed to localeapp and not Yarn. E.g. yarn localeapp pull -- --raw.

Options

$ localeapp push [locale]

This option allows you to push a particular locale to the remote Localeapp project. Can be useful when pushing existing non-default translations to Localeapp. E.g. localeapp push fr will push the fr.yml file.

$ localeapp update --watch

The --watch flag (also available as -w) will enable watching on all files living in the defined source folder (see Setup), and will call the update function on every change.

$ localeapp pull --raw
$ localeapp push --raw

The --raw flag will skip building sources when pulling from Localeapp. This is available in case you are using localeapp simply to communicate with the remote project, and the source folders feature is not used.

Folder structure

Here is what a typical translation key file might look like:

en:
  topics:
    title: Some of the topics we cover
    marketing:
      title: Marketing
      feedback: Leave us some feedback!
      user_action:
        save: Save file
        cancel: Cancel
    tech:
      code: This is the code we use
      installation: How to install our software
  meta:
    meta_1: Our brand
    meta_2: Follow us
  username: Your username
  password: Your password
  welcome: Welcome aboard!

It is safe to assume that any large website can grow up to having more than 1000 of these keys. Thus to arrange keys into categories (folders), something like the following might be easier to search and maintain:

src
│
├── topics/
│   ├── marketing/
│   │   ├── index.yml
│   │   ├── newsletters.yml
│   │   └── website.yml
│   │
│   ├── tech/
│   │   └── index.yml
│   │
│   ├── index.yml
│   └── manifest.json
│
├── index.yml
└── manifest.json

Where the contents of the index.yml (or other names .yml) files only contain key-value pairs, and the manifests contain the description of the folders within that directory. Thus the manifest in the topics folder would describe:

{
  "marketing": "{{marketing}}",
  "technology": "{{tech}}"
}

The key defines the actual translation key, and the value specifies the folder where the tool will look for the child keys. This is done so that one can name a folder differently from the actual key name. The index file in the marketing folder contains the keys found under the marketing key in the large file above.

The general consensus is that:

  • Any keys shared between folders (somewhat categories) should go in the index.yml at the root of each folder
  • Keys shared between between elements (e.g. the different files within a folder without manifest.json) should go in the index.yml at the root of that folder. topics/marketing/index.yml in the example above for keys shared between newsletters and website
  • Keys only used in a particular element should live within that file and are not used anywhere else; newsletter.yml or website.yml in the example above

You may follow this example as a template for your own project. Here you can see the full example above with the folders and compiled file.

Credits

This repository was initially a fork from the louki package.

License

MIT. See LICENSE for details.