Creating Locales

Locales are simple .js JavaScript files. Bogus is using a direct copy of locales from faker.js, so keeping up with the original node.js format is necessary for compatibility between both projects. Ideally, we'd like to keep both faker.js and Bogus locales in sync so both projects can benefit from the community locale contributions.

You have two options:

1. Submit your locale updates to faker.js. (recommended)
2. Submit your locale updates to Bogus. (not recommended)

When possible, please use the recommended first option.

Option 1: Submitting locale updates to faker.js

First, go to the main faker.js repo and submit a pull request for your new locale.

Second, when your pull request is accepted by the main faker.js repo, add an issue to Bogus and we'll update our faker.js locales to use the latest locale data set.

Note about array ordering

If you're updating a locale be sure to add items at the end of an array not the beginning of an array. Adding items at the beginning of an array might break some unit tests based on our seeded test value. Ideally, please run all unit tests before submitting a pull request for maximum acceptance awesomeness.

Option 2: Submitting locale updates to Bogus

If there is some overwhelming reason not to submit your new locale data to faker.js and you would rather submit your data to Bogus, then please use the following guidelines to make sure your Pull Request is accepted.

Please keep in mind, changes to Bogus' locale data must pass strict tests for Quality Assurance and all Pull Requests carry a high-bar for acceptance. Please be responsive to any change requests by maintainers to help carry your Pull Request across the finishing line with maximum awesomeness.

✔️ First create a GitHub issue that outlines what you'd like to change or add. This is a great way to let everyone know what you'll be working on.

✔️ Follow the guidelines for array ordering as mentioned in the previous section above.

✔️ Extra data added to locales should be kept reasonably small. Don't overdo it, but still provide enough data to give some semblance of randomness. The Bogus.dll file is already 2MB and we want to try to keep it as small and compact as possible.

✔️ All data modifications, additions, and improvements to any locale must go in the data_extend folder unless explicitly stated otherwise (as below).

❌ Do not modify existing files in the data folder. The data folder is auto-generated during the build process and any changes or modifications will be overwritten. The only time it is safe to ignore this guideline is if you are adding a completely new locale that both Bogus and faker.js are not aware of.

💡 Bogus merges the data_extend\*.locale.json folder with the upstream faker.js locales, then outputs the result in the data\*.locale.json folder. This is done primarily to keep up with faker.js locales, while at the same time, still giving us the ability to modify and improve locale data for Bogus users.

The process to update/change or add locales is outlined as follows:

1. Create an issue; let us know your intent. Fork the Bogus repo.

2. Are you creating a new locale that Bogus and faker.js don't know about? If you are, simply create the locale in data\__.locale.json where __ is your new locale code. Your data won't get clobbered over since it never gets picked up upstream in faker.js. Skip to Step 6.

3. Are you modifying an existing locale? Create a file in data_extend folder if one doesn't already exist. The name of the file should match exactly the name of the locale you wish to modify in the data folder. For example, if you want to update the data\es.locale.json locale, then create a file in data_extend\es.locale.json.

4. Next, find the JSON Path and Key of the data in the locale you want to modify.

   • For example, let's add new commerce colors to the es locale. Since the es locale already defines data\es.locale.json -> commerce.color, we'll need to copy the whole array to data_extend\es.locale.json -> commerce.color folder and then add our new colors.

   data_extend\es.locale.json:

   { //This is the "data_extend\es.locale.json" extend file.
     "commerce": {
       "color": [
         "Rojo",     <-\
         "Azul",     <--\
         "Verde",    <--- copied array data from
         "Morado",   <--/     data\es.locale.json : commerce.color.
         "Violeta",  <-/
         "My New Color 1", <-\
         "My New Color 2", <-- new color additions
         "My New Color 3"  <-/
       ]
   }
   

5. Next, open a command prompt and cd Source\Builder\ and execute gulp importLocales.

   C:\Bogus\Source\Builder> gulp importLocales 
   

   Note: You'll need node.js installed and gulp installed as a global tool.

   Finally, you'll get some output. Check and make sure your data modifications are appearing in the data\ folder and that the locale you are targeting has been modified.

6. Verify all unit tests are passing. Fix all failing unit tests. If your locale is completely new, add a unit test in Bogus.Tests\LocaleTests to ensure the new locale is picked up and being read correctly.

7. Send in your Pull Request and we'll review it!