This feature is available from the Essential plan and above.
Jira is a software development tool used by agile teams. In this guide, you'll learn how to set up Jira Cloud and Jira Server apps, and how to manage your Jira app on Lokalise.
Enabling Jira Cloud app
To enable the Jira Cloud app, open your Lokalise project and go to the Apps page:
Find Jira Cloud in the list, click on it, and then click Install. Click Install again and log in with your Atlassian account. Give Lokalise access to your workspace, and you’re good to go!
Enabling Jira Server app
To get started with the Jira on-premises app, follow these steps:
Open your translation project on Lokalise and go to Apps.
Find Jira Server in the list and click Install.
Click Install once again. You'll see the following screen:
Note: Providing the Internal hostname is optional. This parameter is for customers using a proxy to isolate their Jira Server instance from the Internet. Refer to the Note on Internal hostname option for more details.
Click on the "following public key" link and download the public key to your PC.
Go to Jira, click the Cog icon in the top right corner, and choose Applications (admin access required):
Choose Application links from the left menu and enter
https://lokalise.comin the URL text field. Click Create new link.
Enter the Application name (e.g., "Lokalise") and click Continue.
After the application is created, click on the Pen icon next to its name.
Switch to the Incoming Authentication tab and enter the following info:
Consumer key: Provide a combination of random letters and numbers. This key should be supplied to Lokalise.
Consumer name: Enter "lokalise"
Public key: Paste the public key obtained from Lokalise earlier (open the downloaded file with any text editor).
Hit Save and return to Lokalise.
Enter your Jira URL and the consumer key that you provided when setting up Incoming Authentication.
Click Authorize and allow access for Lokalise:
This is it! You can find additional info in the official Jira documentation.
Note on the Internal hostname option
The Internal hostname option should be provided only if you are using a proxy and your Jira Server instance is not accessible from the Internet.
For example, if your Jira Server is accessible through a VPN as jira.example.com, Lokalise cannot reach it because a VPN service is used. However, you can use a different URL, like external.jira.example.com, that proxies requests to internal instances and is accessible from the Internet.
In this case, you'll have mismatching URLs: the Site URL in Jira Server System settings is configured as jira.example.com but requests are sent to external.jira.example.com. This will result in request authorization failure. Therefore, we've introduced the Internal hostname setting so you can provide both the URL available to Lokalise and the original URL from Jira Server system settings. In this scenario, set the URL to external.jira.example.com and the Internal hostname to jira.example.com.
Two important points to note:
If you set the Internal hostname option, OAuth token exchange will redirect you to the specified host rather than the URL in the first field.
The Internal hostname configuration expects just the hostname, without
http://and/path/to/somewhere. Therefore, the protocols in both URLs must be consistent. In the scenario above, bothjira.example.comandexternal.jira.example.commust be accessible only via HTTP or only via HTTPS.
Working with Jira app
Once the initial setup is complete, you'll see the following screen:
You can configure the following options:
Organization: Select the Jira organization you want to integrate with Lokalise.
Project: Choose the Jira project within the selected organization.
Create a new Jira issue when: Select one or more events that will trigger the creation of a new Jira issue (ticket). The created issues will be automatically linked to the trigger event.
Change Jira issue status when: Select one or more events that will trigger a Jira issue update. Note that this only applies to issues initially linked to a certain event. For example, if you choose When a translation task is completed > Done, the actual issue will be marked is done only if in the Create a new Jira issue when you've also chosen When a translation task is created, create a new linked Jira issue > Task.
Delete Jira issue when: Select one or more events that will trigger Jira issue deletion. This only applies to issues initially linked to a certain event.
Add comment to the Jira issue when translation task language is completed: This applies to translation tasks. If your tasks include multiple target languages, each language will likely be closed separately as translations are completed. When this option is checked, the corresponding Jira issue will be updated with a brief comment noting which language was closed in the task.
All these options work with any Lokalise branch. For example, if you create a task in any Lokalise branch, this integration can create a new Jira issue regardless of the branch.
When enabling an option, you'll see dropdowns to further customize the chosen options. The elements in these dropdowns will highly depend on your Jira configuration:
To add another handler, click on the Add another handler button at the bottom of the page:
Here's an example of a Jira issue created for a new translation task on Lokalise:
Note on supported issue types
Only issue types that meet the following requirements are available in the app:
The issue type cannot be a subtask.
The following fields must always be present in the issue type (otherwise the issue type will be skipped):
summary
issuetype
project
description
reporter
If a field is not one of the standard fields listed below, it must be set to not required:
summary
issuetype
project
description
reporter