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.

Submit your locale to faker.js master ...

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.

Also one last important reminder ...

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.

Modifying Bogus locales with better data

If for some reason you don't want to submit your new locale data to faker.js and wish to submit your data to Bogus in this repository, 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 carry a high-bar for acceptance.

✔️ First create a GitHub issue that details what you'd like to change or add.

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

✔️ Keep the data you add reasonably small. Don't over do 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:

   {
     "commerce": {
       "color": [
         "Rojo",
         "Azul",
         "Verde",
         "Morado",
         "Violeta",
         "My New Color 1",
         "My New Color 2",
         "My New Color 3"
       ]
   }

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

   C:\Bogus\Source\Builder> gulp import.locales
   

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

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

6. Verify all unit tests are passing. Fix any that fail. If you're 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!