Create and Manage Custom Languages in Site Search

Use custom languages when your Site Search apps need language support beyond the system languages provided by SearchStax. A custom language lets you define a Solr-compatible language configuration at the account level, then add that language to compatible Site Search apps.

Custom languages are intended for multilingual search experiences that need language-specific settings, such as custom stopword lists, custom synonyms, accent normalization, or language-specific tokenization behavior.

How Custom Languages Work

Custom languages are managed in two steps:

1. Create the custom language for the account. Define the language name, language code, app platform, language schema JSON, and supporting language files.
2. Add the custom language to compatible apps. After you add the language to an app, configure the language-specific search experience as you would for other app languages.

Only custom languages that match an app's platform are available when you add a language to that app.

For example, a custom language created for the Drupal platform is available only for compatible Drupal apps. A custom language created for the Sitecore platform is available only for compatible Sitecore apps.

To use the same language across multiple platforms, create a separate custom language definition for each platform.

System Languages and Custom Languages

Site Search includes two types of languages:

Custom languages are created at the account level. After you create a custom language, you can add it to compatible Site Search apps in that account.

Note: Custom languages aren't shared across accounts.

Who Can Manage Custom Languages?

The following roles can manage account-level languages:

• Owner
• Administrator
• Developer

Other roles can't create, edit, or delete account-level custom languages.

What to Prepare Before You Create a Custom Language

Before you create a custom language, prepare the following information and files:

• A display name for the language.
• A language code.
• The app platform for the language configuration: Custom, Drupal, or Sitecore.
• A language schema in JSON format.
• Any supporting .txt language files referenced by the schema.

The schema and supporting files should match the Solr-compatible language configuration you want to define.

Create a Custom Language

Follow these steps to create a custom language for an account:

1. In Site Search, go to Account Settings > Language Management.

2. Click Add Custom Language.
3. In Language Name, enter a display name for the custom language. See Language Name, Code, and Platform Requirements for more information.
4. In Language Code, enter a language code. See Language Name, Code, and Platform Requirements for more information.
5. In Platform, choose the app platform for this language configuration. See Language Name, Code, and Platform Requirements for more information.

6. In Language Schema (JSON), paste the language schema. See Language Schema JSON and Supporting Language Files for more information.
7. Upload any supporting language files referenced by the schema. See Supporting Language Files and Stopword and Synonym Files for more information.
8. Click Save.

After the custom language is saved, it becomes available for compatible apps in the account.

Language Name, Code, and Platform Requirements

The language name must meet these requirements:

• Maximum length: 64 characters.

The language code must meet these requirements:

• Can contain only lowercase letters, numbers, and underscores.
• Maximum length: 16 characters.

The combination of language code and platform must be unique.

Note: A custom language is scoped to one platform. If you need the same language for more than one platform, create a separate custom language definition for each platform.

Language Schema JSON

The language schema must use a Solr-compatible JSON format to define the language. For details about Solr schema commands, see the Apache Solr Schema API Reference Guide.

SearchStax determines whether to create or update schema components based on whether the language is being added or edited.

Don't use duplicate JSON keys. To apply multiple commands of the same type, use list syntax.

Allowed:

{
  "add-field": [
    {
      "name": "new_field"
    },
    {
      "name": "second_field"
    }
  ]
}

Not allowed:

{
  "add-field": {
    "name": "new_field"
  },
  "add-field": {
    "name": "second_field"
  }
}

Use this object order in the schema:

1. Types
2. Fields
3. Copy fields

Any add-field commands listed in the Apache Solr Schema API Reference Guide are supported.

The schema is validated when you leave the JSON editor. You can't save the custom language until the JSON is valid and all required fields pass validation.

Example Language Schema JSON

Schema structure and referenced file paths can vary by platform. Match the example to your platform, and make sure every uploaded filename exactly matches the value referenced in the JSON.

Use the tabs below to switch between the Drupal-specific schema example and the example pattern used for other platforms.

{
  "add-field-type": {
    "name": "text_en_us",
    "class": "solr.TextField",
    "positionIncrementGap": "100",
    "indexAnalyzer": {
      "tokenizer": {
        "class": "solr.StandardTokenizerFactory"
      },
      "filters": [
        {
          "class": "solr.LowerCaseFilterFactory"
        },
        {
          "class": "solr.StopFilterFactory",
          "ignoreCase": "true",
          "words": "stopwords_en_us.txt"
        },
        {
          "class": "solr.KeywordMarkerFilterFactory",
          "protected": "protwords_en_us.txt"
        }
      ]
    },
    "queryAnalyzer": {
      "tokenizer": {
        "class": "solr.StandardTokenizerFactory"
      },
      "filters": [
        {
          "class": "solr.LowerCaseFilterFactory"
        },
        {
          "class": "solr.SynonymGraphFilterFactory",
          "ignoreCase": "true",
          "synonyms": "synonyms_en_us.txt",
          "expand": "true"
        },
        {
          "class": "solr.StopFilterFactory",
          "ignoreCase": "true",
          "words": "stopwords_en_us.txt"
        },
        {
          "class": "solr.KeywordMarkerFilterFactory",
          "protected": "protwords_en_us.txt"
        }
      ]
    }
  },
  "add-dynamic-field": {
    "name": "tm_X3b_en_us_*",
    "type": "text_en_us",
    "indexed": "true",
    "stored": "true"
  }
}

protwords_en_us.txt
stopwords_en_us.txt
synonyms_en_us.txt

{
  "add-field-type": {
    "name": "text_chakobsa",
    "class": "solr.TextField",
    "positionIncrementGap": "100",
    "indexAnalyzer": {
      "tokenizer": {
        "class": "solr.StandardTokenizerFactory"
      },
      "filters": [
        {
          "class": "solr.LowerCaseFilterFactory"
        },
        {
          "class": "solr.StopFilterFactory",
          "ignoreCase": "true",
          "words": "lang/stopwords_chakobsa.txt"
        },
        {
          "class": "solr.KeywordMarkerFilterFactory",
          "protected": "lang/protwords_chakobsa.txt"
        }
      ]
    },
    "queryAnalyzer": {
      "tokenizer": {
        "class": "solr.StandardTokenizerFactory"
      },
      "filters": [
        {
          "class": "solr.LowerCaseFilterFactory"
        },
        {
          "class": "solr.SynonymGraphFilterFactory",
          "ignoreCase": "true",
          "synonyms": "lang/synonyms_chakobsa.txt",
          "expand": "true"
        },
        {
          "class": "solr.StopFilterFactory",
          "ignoreCase": "true",
          "words": "lang/stopwords_chakobsa.txt"
        },
        {
          "class": "solr.KeywordMarkerFilterFactory",
          "protected": "lang/protwords_chakobsa.txt"
        }
      ]
    }
  },
  "add-field": [
    {
      "name": "title_text_chakobsa",
      "type": "text_chakobsa",
      "indexed": "true",
      "stored": "true"
    },
    {
      "name": "body_text_chakobsa",
      "type": "text_chakobsa",
      "indexed": "true",
      "stored": "true"
    }
  ],
  "add-dynamic-field": {
    "name": "*_text_chakobsa",
    "type": "text_chakobsa",
    "indexed": "true",
    "stored": "true"
  }
}

protwords_chakobsa.txt
stopwords_chakobsa.txt
synonyms_chakobsa.txt

Upload all files referenced in the schema before saving the custom language. Don't upload supporting files that aren't referenced in the schema.

Supporting Language Files

You can upload supporting language files when you create or edit a custom language.

Supporting files must meet these requirements:

• File type: .txt
• Maximum file size: 10 MB per file
• Maximum number of files: 10 files

Uploaded files appear in the files table after they pass validation.

If your schema references supporting files, upload all referenced files before saving. Site Search validates the referenced files when you save the custom language.

Stopword and Synonym Files

For compatibility with Site Search features, stopwords and synonyms files must use these naming conventions:

stopwords_<languagecode>.txt
synonyms_<languagecode>.txt

For example, if the custom language code is en_uk_custom, the file names should be:

stopwords_en_uk_custom.txt
synonyms_en_uk_custom.txt

If synonyms and stopwords are included in the uploaded language files, they're automatically truncated and aren't fully applied.

To use stopwords and synonyms with a custom language, reference the stopwords_<languagecode>.txt and synonyms_<languagecode>.txt files in the language schema and upload those files when you create the custom language.

The uploaded stopword and synonym files aren't the long-term source of truth for app-level stopwords and synonyms.

After you add the custom language to an app, manage synonym and stopword entries from the app's Synonyms and Stopwords configuration pages. Use the same workflow that you use for system languages.

Validate the Schema and Files

To save a custom language, the following must be true:

• The language code and platform combination is unique.
• The schema is valid JSON.
• All files referenced in the schema have been uploaded.
• Uploaded files meet the file type, file size, and file count requirements.

Add a Custom Language to an App

After you create a custom language, add it to each compatible app where you want to use it.

1. Open the Site Search app.
2. Go to App Settings > Languages.
3. Click Add Language.
4. Choose All, Custom, or System from the filter.
5. Select the custom language.
6. Optional: Turn on Make Default if this language should be the default language for the app.
7. Click Add Language.
8. Click Save.

Only custom languages that match the app platform are available in the app's Add Language window.

After You Add a Custom Language to an App

After you add a custom language to an app, configure and test the search experience.

Next steps:

1. Select the custom language in the app.
2. Configure search settings, such as Search Fields and Results Fields.
3. Add synonyms and stopwords through the app's Synonyms and Stopwords configuration pages, if needed.
4. Ingest data for the language. Depending on your setup, this might happen through crawling, custom scripts, or re-indexing through connectors.
5. Test the language in Search Preview.

Site Search makes the needed schema changes. You don't need to reload the schema manually.

Edit a Custom Language

You can edit custom languages from the account-level Language Management page.

1. In Site Search, go to Account Settings > Language Management.
2. Find the custom language.
3. Click the edit icon.
4. Update the language name, schema, or supporting files.
5. Optional: Scroll to Apply Schema Changes to Selected Apps (Optional) and use Select Apps to choose the apps where you want to apply the updated schema. The app selector is searchable and groups apps by environment.
6. Click Save.

You can't change the following properties after a custom language is created:

• Language Code
• Platform

Changes are saved at the account level and are used when the language is added to new apps.

Updates aren't automatically applied to apps where the custom language is already in use. To apply changes to existing apps, select those apps during the edit workflow.

Apply Schema Changes to Apps

When you edit an existing custom language, you can apply the updated schema to selected Site Search apps.

Only eligible apps are available for selection. An app is eligible when both of the following are true:

• The app uses the same platform as the custom language.
• The app already has the custom language added.

No apps are selected by default.

If you save changes without selecting any apps, the custom language is updated only at the account level. Existing apps that already use the language aren't updated.

If you select one or more apps, Site Search saves the account-level language changes and applies the updated schema to the selected apps.

After you apply schema changes to an app, ingest data for the language again. Depending on your setup, this might happen through crawling, custom scripts, or re-indexing through connectors.

Site Search makes the needed schema changes. You don't need to reload the schema manually.

Update Supporting Files

When you update supporting files for a custom language, the new files replace the existing files for the account-level custom language.

Stopwords and synonyms files are an exception. You can't edit or delete stopwords_<languagecode>.txt or synonyms_<languagecode>.txt from the custom language edit page. To manage synonyms and stopwords, use the app's Stopwords and Synonyms configuration pages after you add the custom language to the app.

File changes aren't automatically applied to existing apps that already use the language. To apply file or schema changes to existing apps, select the apps during the edit workflow.

Custom languages don't keep version history. After you save changes, previous schema or file configurations can't be restored.

Delete a Custom Language

You can delete custom languages from the account-level Language Management page.

Note: Languages can only be deleted when they aren't used by any apps.

1. In Site Search, go to Account Settings > Language Management.
2. Find the custom language.
3. Click the delete icon.

4. Review the confirmation message and click Delete.

Deleting a custom language permanently removes it from the account. This action can't be undone.

If a custom language is used in one or more apps, the delete action is unavailable. Remove the language from those apps before deleting it from the account.

System languages can't be deleted.

Copy Apps with Custom Languages

When you copy a Site Search app, custom languages configured in the source app are copied to the destination app.

This includes:

• The custom language associations enabled in the source app.
• App-level language settings, such as the default language.

Troubleshooting

I Can't Save the Custom Language

Check the following items:

• All required fields are complete.
• The language name is 64 characters or fewer.
• The language code uses only lowercase letters, numbers, and underscores.
• The language code is 16 characters or fewer.
• The language code and platform combination is unique.
• The schema JSON is valid.
• All schema-referenced files have been uploaded.
• Uploaded files use the supported .txt file type.
• Uploaded files are 10 MB or smaller.
• No more than 10 files are uploaded.

I Don't See the Custom Language When Adding a Language to an App

Custom languages appear only for compatible app platforms. Confirm that the app platform matches the platform selected when the custom language was created.

To check the custom language platform, go to Account Settings > Language Management.

To check the app platform, go to the Dashboard and review the Search Apps table.

If the platforms don't match, create a new custom language for the correct platform.

I Can't Delete a Custom Language

You can delete a custom language only when it isn't used by any app.

To delete it:

1. Go to each app that uses the custom language.
2. Remove the custom language from those apps.
3. Return to Account Settings > Language Management.
4. Delete the custom language.

Search Results Didn't Change After Updating a Custom Language

After you update a custom language, apply the changes to the apps that should use the updated schema.

1. Go to Account Settings > Language Management.
2. Edit the custom language.
3. Select Apply Schema Changes to Selected Apps.
4. Select the relevant apps.
5. Click Save.
6. Ingest data for the language again.

Site Search makes the needed schema changes. You don't need to reload the schema manually.