Language injection is the way the IntelliJ Platform handles different languages within the same source file. Well-known examples are:
Regular expressions in Java string literals
SQL queries in Java string literals
Fenced code blocks within Markdown files
Injected code is always bound to a specific context that depends on the surrounding code, and the IntelliJ Platform treats injected fragments as separate small files that are in a different language. To ensure highlighting and code-insight features work correctly, these fragments must be a valid statement or expression in the injected language. The three examples from above would then be shown like this in IntelliJ IDEs:
It's not unusual that injected fragments are distributed among, e.g., several strings that are concatenated like it is common for SQL queries. To solve this, the IntelliJ Platform allows injecting a language into several fragments at once. Multiple parts are then considered belonging together.
As a plugin author, you can provide language injection in different ways:
For simple cases, the bundled IntelliLang plugin can handle injections, and plugin authors need to provide a configuration with patterns that specify the context where languages should be injected. IntelliLang can also be extended to support unknown custom languages.
com.intellij.languageInjectionContributorextension point (EP) provides a high-level API for the injection of other languages. For more control over how a language is injected, plugin authors use the
com.intellij.multiHostInjectorEP gives plugin authors the most control over where and how language injection will take place.
In the following sections, we'll discuss these three options in more detail.
First, please read the available documentation on IntelliLang. A good point to start with is to inspect available language injections that you can find in the IntelliLang settings under . The injections shown are configured through XML files and loaded automatically.
Let's take a look at the Java
String.matches() method that injects the RegExp language into the string of the first argument. In the IntelliLang settings, it is defined as one possible injection in Java code.
Double-clicking on this entry shows the exact context where a RegExp can be injected, and
String.matches() is one of several possibilities. On the plugin side, these entries are defined in the file
The XML file with the injection configurations is loaded through the
org.intellij.intelliLang.injectionConfig EP in the file
It is important to make a distinction between plugin authors who want to provide injections into existing languages and plugin authors who want to provide support for IntelliLang injections in their custom language. Both define their injections by providing XML configurations and loading them through the plugin.xml. However, custom language authors need to implement the
org.intellij.intelliLang.languageSupport EP to make their language and PSI element patterns known to IntelliLang. Therefore, plugin authors who want to provide injections for known languages can skip the first step.
Implement org.intellij.intelliLang.languageSupport EP
org.intellij.intelliLang.languageSupport EP and use
AbstractLanguageInjectionSupport as a base class. Please refer to the API docs of
LanguageInjectionSupport for information on methods to override and use
JavaLanguageInjectionSupport as an example implementation.
Create Injection Configuration
Create an XML file with the injection configuration. You can export existing injections from the IntelliLang settings to create a template and then edit it. Element patterns are used to specify the context where injections will take place. Custom language authors can use the specific patterns returned from their implementation of
injection tag requires the attributes
injector-id. The first one specifies the
Language.getID()) of the language that is injected. The second one is the id of the host language (see
JavaLanguageInjectionSupport.getId()). For instance, injecting SQLite into Python code is specified by the following opening tag:
Inside an injection, the following tags can be used:
A short name for the injection.
The element pattern that defines where an injection will take place. The content is wrapped in
Static content that is wrapped around the injected code, e.g., to make it a valid expression. For example, to a CSS color specification inside a string, it can be wrapped with the prefix
A regex for the content that specifies when this injection should be applied. Regex groups can specify the text range of the injection (e.g.
A regex for the content that specifies when this injection should not be applied.
Create an XML File to Load the Configuration
Create an XML file myLanguageID-injections.xml next to your plugin.xml that loads the above configuration. Custom language authors also register their implementation of the
languageSupport EP there.
Load the Injection Configuration in plugin.xml
The injections are an optional dependency that only works when IntelliLang is enabled. Therefore, you load the configuration optionally in your main plugin.xml:
LanguageInjectionContributor and LanguageInjectionPerformer
com.intellij.languageInjectionContributor EP provides injection information for the given context in terms of what to inject. As a plugin author, implement
LanguageInjectionContributor to provide context-specific injections.
For instance, if you want to inject a YAML or JSON to a literal language depending on some conditions, you could implement this interface like this:
Register the implementation in your plugin.xml:
If you want more control over how the injection should be done then implement the
com.intellij.languageInjectionPerformer EP which allows for complex language injections, e.g. for concatenation or interpolation of strings. If it is not implemented, then the
DefaultLanguageInjectionPerformer will be used.
com.intellij.languageInjectionPerformer EP, two methods need to be implemented in
isPrimary() determines if this is the default
LanguageInjectionPerformer for the language and if it handles most of the injections. If there is no primary
LanguageInjectionPerformer found, then a fallback injection will be performed.
performInjection() does the actual injection into the context PSI element and/or some elements around it if needed in case if they are semantically connected (concatenation injection for instance).
MultiHostInjector registered in
com.intellij.multiHostInjector EP is a very low-level API, but it gives plugin authors the most freedom. It performs language injection inside other PSI elements, e.g. inject SQL inside an XML tag text or inject regular expressions into Java string literals.
Plugin authors need to implement
getLanguagesToInject() to provide a list of places to inject a language, and
elementsToInjectIn() to return a list of elements to inject.
For example, inject regular expressions into Java string literal:
Register the implementation in your plugin.xml:
A more complex example is when you need to inject into several fragments at once. For example, if we have an XML-based DSL:
which should be converted to the equivalent Java code:
Here, we need to inject Java into several places at once, i.e. method name and its body:
Now, inside the editor the injected portion will work as expected where foo is the method name and
System.out.println(42); will look and feel like a method body with highlighting, completion, and goto definition working.
To control delegation of formatting to containing file, implement
InjectedFormattingOptionsProvider and register in
com.intellij.formatting.injectedOptions extension point (2022.3).