Dictionary: Add configurable value search functionality

[Nis-Knowit]

Summary

This PR adds the ability to search dictionary items by their translation values in addition to keys.
The feature is opt-in via configuration and is disabled by default to preserve backward compatibility and performance.

---

Changes

1. New Configuration Setting

• Created DictionarySettings.cs
  • New configuration class for dictionary-specific settings
• Added EnableValueSearch property
  • Boolean flag to enable value searching
  • Default: false
• Registered in Constants-Configuration.cs
  • Added ConfigDictionary constant
• Registered in DI container
  • Added to UmbracoBuilder.Configuration.cs

---

2. Repository Updates

• Modified DictionaryRepository.cs
  • Injected IOptions<DictionarySettings> into constructor
  • Updated GetDictionaryItemDescendants to support value search when enabled
• Search behavior:
  • When enabled, SQL queries search:
    • cmsDictionary.key using LIKE 'filter%'
    • cmsLanguageText.value using LIKE '%filter%'
  • When disabled, original behavior is preserved (key search only)

---

3. Test Updates

• Updated DictionaryRepositoryTest.cs
  • Added DictionarySettings parameter to test setup

---

Configuration

To enable dictionary value search, add the following to your appsettings.json:

{
  "Umbraco": {
    "CMS": {
      "Dictionary": {
        "EnableValueSearch": true
      }
    }
  }
}

---

Search Behavior

When EnableValueSearch == false (Default)

• Searches only in dictionary keys
• Uses key LIKE 'searchterm%' (starts with)
• Maintains existing performance characteristics

When EnableValueSearch == true

• Searches in both dictionary keys and translation values
• Uses:
  • key LIKE 'searchterm%'
  • value LIKE '%searchterm%'
• Key search uses starts with
• Value search uses contains

---

Performance Testing

Tested with:

• 1,000 dictionary items
• 8 active languages:
  • en-US, sq, da-DK, nb-NO, sv-SE, de-DE, fr-FR, es-ES
• 8,000 total translations

Results:

• Average response time: 20–30 ms
• Search scope: All descendants with filter applied
• Database: SQL Server LocalDB
• Performance is acceptable for typical dictionary sizes in production environments

Umbraco Docs link: umbraco/UmbracoDocs#7734

[github-actions]

Hi there @Nis-Knowit, thank you for this contribution! 👍

While we wait for one of the Core Collaborators team to have a look at your work, we wanted to let you know about that we have a checklist for some of the things we will consider during review:

• It's clear what problem this is solving, there's a connected issue or a description of what the changes do and how to test them
• The automated tests all pass (see "Checks" tab on this PR)
• The level of security for this contribution is the same or improved
• The level of performance for this contribution is the same or improved
• Avoids creating breaking changes; note that behavioral changes might also be perceived as breaking
• If this is a new feature, Umbraco HQ provided guidance on the implementation beforehand
• 💡 The contribution looks original and the contributor is presumably allowed to share it

Don't worry if you got something wrong. We like to think of a pull request as the start of a conversation, we're happy to provide guidance on improving your contribution.

If you realize that you might want to make some changes then you can do that by adding new commits to the branch you created for this work and pushing new commits. They should then automatically show up as updates to this pull request.

Thanks, from your friendly Umbraco GitHub bot 🤖 🙂

[AndyButland]

Looks good to me @Nis-Knowit, apart from one issue that I'll raise as a concern.

Firstly though I have pushed a small update to:

• Rename the configuration key to EnableValueSearch - I felt we didn't need to repeat Dictionary given we are in that configuration section, so the name could be a bit terser.
  • I noted you had already made a docs PR which is great, but if we go with this changed name, that'll need an update too.
• I added a couple of integration tests to verify the functionality.

The problem I found though in testing is that, when I have the feature enabled, if I search for a value that exists on one language, the other language is marked as not having a translation, even though it does.

E.g. in this case, I have both an English and Italian translation, but having search for the Italian one, the English one shows as missing:

So we would need to find a solution to that. I think it may have to be done with a sub-query.

[Nis-Knowit]

@AndyButland I've added a fix to the query that makes sure it returns all languages with a value in the overview :)

[AndyButland]

Looks to work nicely @Nis-Knowit. I just pushed an update to use IOptionsMonitor and to extend the integration test to verify the fix to the issue I found.

Just curious how this update has affected the performance you provided a benchmark for when you first raised the PR? I'm assuming the sub-query will be slower than what you first had, but would like to understand by how much.

[Nis-Knowit]

@AndyButland
Based on your debug output, here's the formatted performance test results:

Performance Testing

Test Environment:
• 1,003 dictionary items
• 8 active languages: en-US, sq, da-DK, nb-NO, sv-SE, de-DE, fr-FR, es-ES
• 8,024 total translations
• Database: SQL Server LocalDB
• Search configuration: EnableValueSearch = true

Results:
Search Filter Response Time Results Returned Query Type
Empty (all items) 27ms 1,003 Root fetch
"English " (value search) 36ms 999 Root fetch with value search

Performance Metrics:
• Average response time: 27-36ms
• Search scope: All descendants with subquery-based value filtering
• Query optimization: Subquery approach successfully retrieves all translations for matching dictionary items

Conclusion:
The subquery-based approach for value search performs well with 1,000+ dictionary items:
• Response times remain under 40ms for both full dataset retrieval and filtered value searches
• The subquery optimization (IN (SELECT DISTINCT UniqueId...)) efficiently identifies matching dictionary items while retrieving all their translations
• Performance is acceptable for typical dictionary sizes in production environments
• No significant performance degradation when searching translation values compared to retrieving all items

[AndyButland]

That sounds promising @Nis-Knowit, thanks. Then I see no reason not to merge this in, so I'll approve, and we'll have this available from 17.2.

Thanks for the docs PR too. I'll add some comments on there just to get that ready for when we make available the release candidate for 17.2.