Languages

zxcvbn-ts is available for multiple languages. If your language is not supported you can set the options by yourself.

Current supported languages:

• Arabic
• Czech
• Croatian
• Danish (Denmark)
• German
• English
• Spanish (Spain)
• Farsi (Persian)
• Finnish
• French
• Indonesia
• Italian
• Japanese
• Kurmanjî (Kurdish)
• Dutch (Belgium)
• Polish
• Portuguese (Brazil)
• Romanian
• Thai
• Chinese
• Turkish

Feedback

By default, zxcvbn-ts uses keys as feedback. This way you can integrate zxcvbn-ts into your own translation system. If you don't have an own translation system or want to use predefined translation you can use one of the language packs. Each language pack has its own translation file that you can use like this:

import { ZxcvbnFactory } from '@zxcvbn-ts/core'
import { translations } from '@zxcvbn-ts/language-en'

const password = 'somePassword'
const options = {
  translations,
}

const zxcvbn = new ZxcvbnFactory(options)
zxcvbn.check(password)

Pluralization

For the timeEstimation translations, you can use a string with a {base} placeholder or a function for more complex pluralization rules.

const translations = {
  warnings: {
    // ...
  },
  suggestions: {
    // ...
  },
  timeEstimation: {
    ltSecond: 'less than a second',
    second: '{base} second',
    seconds: (value) => {
      if (value === 2) return 'exactly two seconds'
      return `${value} seconds`
    },
    // ...
  },
}

Dictionary

By default, zxcvbn-ts doesn't use any dictionaries to let the developer decide how much of the library will be used. This makes the library tiny but inefficient compared to the original library. It is recommended to use at least the common and english language package.

import { ZxcvbnFactory } from '@zxcvbn-ts/core'
import * as zxcvbnCommonPackage from '@zxcvbn-ts/language-common'
import * as zxcvbnEnPackage from '@zxcvbn-ts/language-en'

const password = 'somePassword'
const options = {
  dictionary: {
    ...zxcvbnCommonPackage.dictionary,
    ...zxcvbnEnPackage.dictionary,
  },
}

const zxcvbn = new ZxcvbnFactory(options)
zxcvbn.check(password)

Keyboard patterns

By default, zxcvbn-ts don't use any keyboard patterns to let the developer decided how much of the library will be used. It is recommended to use at least the common keyboard patterns.

import { ZxcvbnFactory } from '@zxcvbn-ts/core'
import * as zxcvbnCommonPackage from '@zxcvbn-ts/language-common'

const password = 'somePassword'
const options = {
  graphs: zxcvbnCommonPackage.adjacencyGraphs,
}

const zxcvbn = new ZxcvbnFactory(options)
zxcvbn.check(password)

Add a new language package

To add a missing language package you need to do the following things:

• Clone the repo.
• Install dependencies with yarn install.
• Create a new language package inside the packages/languages directory. You need following file structure:

- src
  - translations.ts
- package.json
- README.md
- tsconfig.json

• Fill src/translations.ts with translations for your language. You can use strings with {base} or functions for timeEstimation if your language has complex pluralization rules.

• Adjust README.md file as appropriate.

• Find some reliable sources for some dictionaries. As a minimum, you need to have a source for firstname, lastname and commonWords. For common words you can check out https://github.com/hermitdave/FrequencyWords - there are a lot of languages available.

• Add your language and sources to the generator list in ./data-scripts/lists.ts.

  There is a default generator that takes simple lists that have only single words per line and can have occurrences of that word with a space separator. For example something like this:

  John
  Debra
  Billy
  

  or:

  you 23123
  i 12345
  the 234
  

  If your list is more complex you need to write your own generator like the password generator or the keyboard generator

• Run yarn generate:languageData. This will generate the JSON files and index.ts.

• During debugging, it might be easy to only generate the language files for one language, use yarn generate:languageData nl-be for example.

• Create a pull request to the master branch.

• (Optional) Use the Wikipedia extractor; one of the maintainers can do this but this will increase the time until it is merged.

  • Get the wikipedia dump for your language from https://dumps.wikimedia.org/XXwiki/latest/XXwiki-latest-pages-articles.xml.bz2 where XX is your language like en or de.

  • Install wikiextractor: pip install wikiextractor. Currently, with v3.0.4 it only works correctly on Linux.

  • Run wikiextractor:

    wikiextractor --no-templates -o data-scripts/wikiExtractor/extracts XXwiki-latest-pages-articles.xml.bz2
    

  • Run yarn run wikipediaExtractor to generate wikipedia.json from all the files inside the extracts folder.

  • Move wikipedia.json into your language package.