This README is about setting up your own instances of Nimiq Keyguard.
For information about using the client please refer to the Keyguard Client README.
Install the dev dependencies:
yarn
Then you can:
- serve the Keyguard locally with
yarn serve
(starts on port 8000). - run the build script with
yarn build [config]
. - run the tests with
yarn test
. - run the typechecker with
yarn typecheck
. - run the typecheck file watcher with
yarn watch
. - run the linter with
yarn lint
. - automatically fix basic things like spacing, commas, indentation and quotes
with
yarn lintfix
. - run
yarn pr
to run all three checks (typecheck
,lint
,test
) as they would for a PR.
Note that it is mostly not necessary to run the build script for development purposes, as the code in src
is fully
functional and you can use it as an endpoint. Only regenerating the translation dictionary needs to be triggered
manually by restarting yarn serve
or by running yarn i18n:build-dictionary
.
For convenient testing of the Keyguard there are demos provided under /demos
.
- Code style is enforced with ESLint. Run
yarn lint
to see errors. - Folder names are in Kebab Case:
sign-transaction
. - Class files are named in Pascal Case:
PinInput.js
,RpcServer.js
. - JSDoc @type and @param annotations must have a hyphen between the argument name and description:
/**
* @param {string} address - The address to search for
*/
- Folder structure:
- src
- assets
- components
- config
- lib
- request
- translations
- types
- tests
- tools
- demos
- client
- src
- types
You can configure the following values by configuration files located in folder src/config
:
- ALLOWED_ORIGIN: The origin from which requests are accepted. '*' allows all origins.
- NETWORK: The network to connect with. Use Constants.NETWORK constants.
- ROOT_REDIRECT: The page where the user is redirected to when accidentally going to root URL.
The config file used for unbuilt code is config.local.js
. The build script uses config.testnet.js
by default. To use
a different file (especially useful for deployment), pass its name as an argument to the build script.
yarn build mainnet
uses config.mainnet.js
.
First, import the I18n.js
lib in your HTML's head section. Then, setup your
dictionary (details see below) and initialize I18n
passing your dictionary
and the fallback language that should be used if no translation in the current
language has been found.
var myDictionary = {
'en': {
...
}
};
I18n.initialize(myDictionary, 'en');
The Keyguard uses an app wide dictionary auto-generated from separate language files, see section Contribute to translations.
I18n
will by default use the language specified in a lang
cookie if present
or otherwise fallback to the browser's language or English.
<div data-i18n="my-translation">My content</div>
When the I18n gets started, or when the language has been switched, it will look
for tags with the data-i18n
attribute and put in the appropriate translation.
My content
will be replaced.
<input data-i18n-placeholder="my-placeholder-translation"/>
<input data-i18n-value="my-value-translation"/>
Similarily, I18n will translate the texts for value and placeholder.
Add LanguagePicker.js
to your head and then add a language picker widget to your
page:
const languagePicker = new LanguagePicker();
document.body.appendChild(languagePicker.getElement());
First of all, a big thank you to all translators!
The Nimiq Keyguard is fully internationalized and ready for the community to add translations in different languages.
To help translate the Keyguard, the procedure is as follows:
-
Clone this repository.
-
The translations are located in the
src/translations
folder. A translation file for a language is named as the language's two letter ISO 639-1 code plus file extension.json
. For example, for French with two letter codefr
the translations are located atsrc/translations/fr.json
. If that file doesn't exist yet, i.e. you're starting a new translation, please duplicateen.json
as starting point and rename it accordingly. -
The translation files are in a key-value json format. For Example:
"my-translation": "Content in English", "timer-expiry": "This offer expires in",
Where the key is the unique identifier of the string to translate. You can find the source string to translate in the
en.json
file. Please only edit the translations, not the source strings nor the keys. -
During the build step, a language dictionary is auto-generated from the separate translation files at
src/translation/index.js
. Please do not edit this file but only the separate translation files. -
You can test your translations locally by setting up a local development server as described in section development and then setting the language cookie in the served page. To do so, open your browser's developer console (ctrl + shift + c) and input
document.cookie = 'lang=<lang>'
where<lang>
should be replaced by the two letter language code of the language you want to test, for exampledocument.cookie = 'lang=fr'
. If you struggle setting up the local demo you can ask us to setup an online demo for you after opening a pull request. -
Once the file has been fully translated or you are done updating an existing translation file, you can open a pull request here in github.
-
The pull request will then be reviewed and, if all goes well, merged into the master branch and published asap.
-
Words between square brackets are html tags which must not be translated nor edited. They will be replaced by a html tag during app runtime. For example:
"recovery-words-intro-offline": "Keep your words offline, enter them nowhere but on [strong]keyguard[/strong].nimiq.com."
-
If you're a transifex collaborator, and need some information about how to get started, here are two links for you:
- How to get started as a translator: https://docs.transifex.com/getting-started-1/translators
- How translate using the web editor: https://docs.transifex.com/translation/translating-with-the-web-editor