Shift docs to root
This commit is contained in:
1 parent
83e627e5c9
commit
91564bfa06
200 files changed
+7
No files matched your search
@@ -0,0 +1,57 @@
|
||||
# Configuration
|
||||
|
||||
> This step assumes you have an imaging archive. If you need assistance setting
|
||||
> one up, check out the [`Data Source` Guide](./data-source.md) or a deployment
|
||||
> recipe that contains an open source Image Archive
|
||||
|
||||
## How it Works
|
||||
|
||||
The configuration for our project is in the `/public/config` directory. Our
|
||||
build process knows which configuration file to use based on the
|
||||
`REACT_APP_CONFIG` environment variable. By default, its value is
|
||||
[`default.js`](https://github.com/OHIF/Viewers/blob/react/public/config/default.js).
|
||||
When we build, the `%REACT_APP_CONFIG%` value in
|
||||
our[`/public/index.html`](https://github.com/OHIF/Viewers/blob/react/public/index.html#L12-L15)
|
||||
file is substituted for the correct configuration file's name. This sets the
|
||||
`window.config` equal to our configuration file's value.
|
||||
|
||||
## How do I configure my project?
|
||||
|
||||
The simplest way is to update the existing default config:
|
||||
|
||||
_/public/config/default.js_
|
||||
|
||||
```js
|
||||
window.config = {
|
||||
routerBasename: '/',
|
||||
relativeWebWorkerScriptsPath: '',
|
||||
servers: {
|
||||
dicomWeb: [
|
||||
{
|
||||
name: 'DCM4CHEE',
|
||||
wadoUriRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/wado',
|
||||
qidoRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs',
|
||||
wadoRoot: 'https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/rs',
|
||||
qidoSupportsIncludeField: true,
|
||||
imageRendering: 'wadors',
|
||||
thumbnailRendering: 'wadors',
|
||||
requestOptions: {
|
||||
requestFromBrowser: true,
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
You can also create a new config file and specify its path relative to the build
|
||||
output's root by setting the `REACT_APP_CONFIG` environment variable. You can
|
||||
set the value of this environment variable a few different ways:
|
||||
|
||||
- [Add a temporary environment variable in your shell](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-temporary-environment-variables-in-your-shell)
|
||||
- [Add environment specific variables in `.env` file(s)](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables#adding-development-environment-variables-in-env)
|
||||
- Using the `cross-env` package in an npm script:
|
||||
- `"build": "cross-env REACT_APP_CONFIG=config/my-config.js react-scripts build"`
|
||||
|
||||
After updating the configuration, `yarn run build:web` to generate updated build
|
||||
output.
|
||||
@@ -0,0 +1,161 @@
|
||||
# Data Source
|
||||
|
||||
After following the steps outlined in [Getting Started](./getting-started.md),
|
||||
you'll notice that the OHIF Viewer has data for several studies and their
|
||||
images. You didn't add this data, so where is it coming from?
|
||||
|
||||
By default, the viewer is configured to connect to a remote server hosted by the
|
||||
nice folks over at [dcmjs.org][dcmjs-org]. While convenient for getting started,
|
||||
the time may come when you want to develop using your own data either locally or
|
||||
remotely.
|
||||
|
||||
## Set up a local DICOM server
|
||||
|
||||
> ATTENTION! Already have a remote or local server? Skip to the
|
||||
> [configuration section](#configuration-learn-more) below.
|
||||
|
||||
While the OHIF Viewer can work with any data source, the easiest to configure
|
||||
are the ones that follow the [DICOMWeb][dicom-web] spec.
|
||||
|
||||
1. Choose and install an Image Archive
|
||||
2. Upload data to your archive (e.g. with DCMTK's [storescu][storescu] or your
|
||||
archive's web interface)
|
||||
3. Keep the server running
|
||||
|
||||
For our purposes, we will be using `Orthanc`, but you can see a list of
|
||||
[other Open Source options](#open-source-dicom-image-archives) below.
|
||||
|
||||
### Requirements
|
||||
|
||||
- Docker
|
||||
- [Docker for Mac](https://docs.docker.com/docker-for-mac/)
|
||||
- [Docker for Windows (recommended)](https://docs.docker.com/docker-for-windows/)
|
||||
- [Docker Toolbox for Windows](https://docs.docker.com/toolbox/toolbox_install_windows/)
|
||||
|
||||
_Not sure if you have `docker` installed already? Try running `docker --version`
|
||||
in command prompt or terminal_
|
||||
|
||||
> If you are using `Docker Toolbox` you need to change the _proxy_ parameter in
|
||||
> _package.json_ to http://192.168.99.100:8042 or the ip docker-machine ip
|
||||
> throws. This is the value [`react-scripts`][react-proxy] uses to proxy
|
||||
> requests
|
||||
|
||||
### Running Orthanc
|
||||
|
||||
_Start Orthanc:_
|
||||
|
||||
```bash
|
||||
# Runs orthanc so long as window remains open
|
||||
yarn run orthanc:up
|
||||
```
|
||||
|
||||
_Upload your first Study:_
|
||||
|
||||
1. Navigate to [Orthanc's web interface](http://localhost:8899) at
|
||||
`http://localhost:8899` in a web browser.
|
||||
2. In the top right corner, click "Upload"
|
||||
3. Click "Select files to upload..." and select one or more DICOM files
|
||||
4. Click "Start the upload"
|
||||
|
||||
#### Orthanc: Learn More
|
||||
|
||||
You can see the `docker-compose.yml` file this command runs at
|
||||
[`<project-root>/docker/Nginx-Docker/`](#), and more on Orthanc for Docker in
|
||||
[Orthanc's documentation][orthanc-docker].
|
||||
|
||||
### Connecting to Orthanc
|
||||
|
||||
Now that we have a local Orthanc instance up and running, we need to configure
|
||||
our web application to connect to it. Open a new terminal window, navigate to
|
||||
this project's root directory, and run:
|
||||
|
||||
```bash
|
||||
# If you haven't already, restore dependencies
|
||||
yarn install
|
||||
|
||||
# Run our dev command, but with the local orthanc config
|
||||
yarn run dev:orthanc
|
||||
```
|
||||
|
||||
#### Configuration: Learn More
|
||||
|
||||
> For more configuration fun, check out the
|
||||
> [Essentials Configuration](./configuration.md) guide.
|
||||
|
||||
Let's take a look at what's going on under the hood here. `yarn run dev:orthanc`
|
||||
is running the `dev:orthanc` script in our project's `package.json`. That script
|
||||
is:
|
||||
|
||||
```js
|
||||
cross-env PORT=5000 REACT_APP_CONFIG=config/docker_nginx-orthanc.js react-scripts start
|
||||
```
|
||||
|
||||
- `cross-env` sets two environment variables
|
||||
- PORT: 5000
|
||||
- REACT_APP_CONFIG: `config/docker_nginx-orthanc.js`
|
||||
- `react-scripts` runs it's `start` script. This is [the de-facto
|
||||
way][cra-start] to run a "Create React App" in development mode.
|
||||
|
||||
The `REACT_APP_CONFIG` value tells our app which file to load on to
|
||||
`window.config`. By default, our app uses the file at
|
||||
`<project-root>/public/config/default.js`. Here is what that configuration looks
|
||||
like:
|
||||
|
||||
```js
|
||||
window.config = {
|
||||
routerBasename: '/',
|
||||
relativeWebWorkerScriptsPath: '',
|
||||
servers: {
|
||||
dicomWeb: [
|
||||
{
|
||||
name: 'Orthanc',
|
||||
wadoUriRoot: 'http://localhost:8899/wado',
|
||||
qidoRoot: 'http://localhost:8899/dicom-web',
|
||||
wadoRoot: 'http://localhost:8899/dicom-web',
|
||||
qidoSupportsIncludeField: false,
|
||||
imageRendering: 'wadors',
|
||||
thumbnailRendering: 'wadors',
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
To learn more about how you can configure the OHIF Viewer, check out our
|
||||
[Configuration Guide](./configuration.md).
|
||||
|
||||
## Open Source DICOM Image Archives
|
||||
|
||||
Our example uses `Orthanc`, but there are a lot of options available to you.
|
||||
Here are some of the more popular ones:
|
||||
|
||||
| Archive | Installation |
|
||||
| --------------------------------------------- | ---------------------------------- |
|
||||
| [DCM4CHEE Archive 5.x][dcm4chee] | [W/ Docker][dcm4chee-docker] |
|
||||
| [Orthanc][orthanc] | [W/ Docker][orthanc-docker] |
|
||||
| [DICOMcloud][dicomcloud] (**DICOM Web only**) | [Installation][dicomcloud-install] |
|
||||
| [OsiriX][osirix] (**Mac OSX only**) | Desktop Client |
|
||||
| [Horos][horos] (**Mac OSX only**) | Desktop Client |
|
||||
|
||||
_Feel free to make a Pull Request if you want to add to this list._
|
||||
|
||||
<!--
|
||||
Links
|
||||
-->
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
[dcmjs-org]: https://server.dcmjs.org/dcm4chee-arc/aets/DCM4CHEE/wado
|
||||
[dicom-web]: https://en.wikipedia.org/wiki/DICOMweb
|
||||
[storescu]: http://support.dcmtk.org/docs/storescu.html
|
||||
[cra-start]: https://github.com/facebook/create-react-app#npm-start-or-yarn-start
|
||||
[react-proxy]: https://facebook.github.io/create-react-app/docs/proxying-api-requests-in-development#configuring-the-proxy-manually
|
||||
<!-- Archives -->
|
||||
[dcm4chee]: https://github.com/dcm4che/dcm4chee-arc-light
|
||||
[dcm4chee-docker]: https://github.com/dcm4che/dcm4chee-arc-light/wiki/Running-on-Docker
|
||||
[orthanc]: https://www.orthanc-server.com/
|
||||
[orthanc-docker]: http://book.orthanc-server.com/users/docker.html
|
||||
[dicomcloud]: https://github.com/DICOMcloud/DICOMcloud
|
||||
[dicomcloud-install]: https://github.com/DICOMcloud/DICOMcloud#running-the-code
|
||||
[osirix]: http://www.osirix-viewer.com/
|
||||
[horos]: https://www.horosproject.org/
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,115 @@
|
||||
# Getting Started
|
||||
|
||||
## Setup
|
||||
|
||||
### Fork & Clone
|
||||
|
||||
If you intend to contribute back changes, or if you would like to pull updates
|
||||
we make to the OHIF Viewer, then follow these steps:
|
||||
|
||||
- [Fork][fork-a-repo] the [OHIF/Viewers][ohif-viewers-repo] repository
|
||||
- [Create a local clone][clone-a-repo] of your fork
|
||||
- `git clone https://github.com/YOUR-USERNAME/Viewers`
|
||||
- Add OHIF/Viewers as a [remote repository][add-remote-repo] labled `upstream`
|
||||
- Navigate to the cloned project's directory
|
||||
- `git remote add upstream https://github.com/OHIF/Viewers.git`
|
||||
|
||||
With this setup, you can now [sync your fork][sync-changes] to keep it
|
||||
up-to-date with the upstream (original) repository. This is called a "Triangular
|
||||
Workflow" and is common for Open Source projects. The GitHub blog has a [good
|
||||
graphic that illustrates this setup][triangular-workflow].
|
||||
|
||||
### Private
|
||||
|
||||
Alternatively, if you intend to use the OHIF Viewer as a starting point, and you
|
||||
aren't as concerned with syncing updates, then follow these steps:
|
||||
|
||||
1. Navigate to the [OHIF/Viewers/tree/react][ohif-viewers-react-repo] repository
|
||||
and branch
|
||||
2. Click `Clone or download`, and then `Download ZIP`
|
||||
3. Use the contents of the `.zip` file as a starting point for your viewer
|
||||
|
||||
> NOTE: It is still possible to sync changes using this approach. However,
|
||||
> submitting pull requests for fixes and features are best done with the
|
||||
> separate, forked repository setup described in "Fork & Clone"
|
||||
|
||||
## Developing
|
||||
|
||||
### Requirements
|
||||
|
||||
- [Node.js & NPM](https://nodejs.org/en/)
|
||||
- [Yarn](https://yarnpkg.com/en/)
|
||||
|
||||
### Kick the tires
|
||||
|
||||
Navigate to the root of the project's directory in your terminal and run the
|
||||
following commands:
|
||||
|
||||
```bash
|
||||
# Restore dependencies
|
||||
yarn install
|
||||
|
||||
# Start local development server
|
||||
yarn start
|
||||
```
|
||||
|
||||
You should see the following output:
|
||||
|
||||
```bash
|
||||
Compiled successfully!
|
||||
|
||||
You can now view ohif-viewer in the browser.
|
||||
|
||||
Local: http://localhost:5000/
|
||||
On Your Network: http://10.74.20.83:5000/
|
||||
|
||||
Note that the development build is not optimized.
|
||||
To create a production build, use yarn build.
|
||||
```
|
||||
|
||||
### 🎉 Celebrate 🎉
|
||||
|
||||
<center>
|
||||
<img alt="development server hosted app" src="/assets/img/loading-study.gif" />
|
||||
<i>Our app, hosted by the development server</i>
|
||||
</center>
|
||||
|
||||
### Building for Production
|
||||
|
||||
> More comprehensive guides for building and publishing can be found in our
|
||||
> [deployment docs](./../deployment/index.md)
|
||||
|
||||
```bash
|
||||
# Build static assets to host a PWA
|
||||
yarn run build:web
|
||||
|
||||
# Build packaged output
|
||||
yarn run build:package
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
...
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- If you receive a _"No Studies Found"_ message and do not see your studies, try
|
||||
changing the Study Date filters to a wider range.
|
||||
- If you see a 'Loading' message which never resolves, check your browser
|
||||
JavaScript console inside the Developer Tools to identify any errors.
|
||||
- If you see any errors in your server console, check the
|
||||
[Troubleshooting](./troubleshooting.md) page for more in depth advice.
|
||||
|
||||
<!--
|
||||
Links
|
||||
-->
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
[fork-a-repo]: https://help.github.com/en/articles/fork-a-repo
|
||||
[clone-a-repo]: https://help.github.com/en/articles/fork-a-repo#step-2-create-a-local-clone-of-your-fork
|
||||
[add-remote-repo]: https://help.github.com/en/articles/fork-a-repo#step-3-configure-git-to-sync-your-fork-with-the-original-spoon-knife-repository
|
||||
[sync-changes]: https://help.github.com/en/articles/syncing-a-fork
|
||||
[triangular-workflow]: https://github.blog/2015-07-29-git-2-5-including-multiple-worktrees-and-triangular-workflows/#improved-support-for-triangular-workflows
|
||||
[ohif-viewers-repo]: https://github.com/OHIF/Viewers
|
||||
[ohif-viewers-react-repo]: https://github.com/OHIF/Viewers/tree/react
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,42 @@
|
||||
# Installation
|
||||
|
||||
It's important to know that the OHIF Viewer project provides two different build
|
||||
processes:
|
||||
|
||||
```bash
|
||||
# Static Asset output: For deploying PWAs
|
||||
yarn run build:web
|
||||
|
||||
# Single `.js` script, for embedding viewer into existing apps
|
||||
yarn run build:package
|
||||
```
|
||||
|
||||
## create-react-app (PWA)
|
||||
|
||||
> [create-react-app](https://github.com/facebook/create-react-app) provides
|
||||
> pre-configured build process for developing front-end applications with
|
||||
> [React](https://reactjs.org/).
|
||||
|
||||
The ohif-viewer package can be run as a create-react-app application. This is
|
||||
useful for development, debugging, or evolving the OHIF Viewer into your own
|
||||
custom imaging application.
|
||||
|
||||
You can read more about this particular strategy in our
|
||||
[Build for Production Deployment Guide](./../deployment/recipes/build-for-production.md)
|
||||
|
||||
## Rollup (Packaged Script)
|
||||
|
||||
> [Rollup](https://rollupjs.org/guide/en) is a module bundler for JavaScript. It
|
||||
> uses the new standardized format for code modules included in the ES6 revision
|
||||
> of JavaScript.
|
||||
|
||||
The [ohif-viewer](https://www.npmjs.com/package/ohif-viewer) package can be
|
||||
built with Rollup to provide a set of React components which can be dropped into
|
||||
a larger application. Specifically, the ohif-viewer package provides a React
|
||||
component named `OHIFViewer` which is the entire viewer, configurable via React
|
||||
`props`. This is useful for including the OHIF Viewer in a larger web
|
||||
application, as the entire application can be provided via a `<script>` tag with
|
||||
no build process required.
|
||||
|
||||
You can read more about this particular strategy in our
|
||||
[Embedded Viewer Deployment Guide](./../deployment/recipes/embedded-viewer.md)
|
||||
@@ -0,0 +1,66 @@
|
||||
# Scope of Project
|
||||
|
||||
The OHIF Viewer is a web based medical imaging viewer. This allows it to be used
|
||||
on almost any device, anywhere. The OHIF Viewer is what is commonly reffered to
|
||||
as a ["Dumb Client"][simplicable]
|
||||
|
||||
> A dumb client is software that fully depends on a connection to a server or
|
||||
> cloud service for its functionality. Without a network connection, the
|
||||
> software offers nothing useful. - [simplicable.com][simplicable]
|
||||
|
||||
While the Viewer persists some data, it's scope is limited to caching things
|
||||
like user preferences and previous query paramaters. Because of this, the Viewer
|
||||
has been built to be highly configurable to work with almost any web accessible
|
||||
data source.
|
||||
|
||||

|
||||
|
||||
To be more specific, the OHIF Viewer is a collection of HTML, JS, and CSS files.
|
||||
These can be delivered to your end users however you would like:
|
||||
|
||||
- From the local networok
|
||||
- From a remote web server
|
||||
- From a CDN (content delivery network)
|
||||
- From a service-worker's cache
|
||||
- etc.
|
||||
|
||||
These "static asset" files are referred to collectively as a "Progressive Web
|
||||
Application" (PWA), and have the same capabilities and limitations that all PWAs
|
||||
have.
|
||||
|
||||
All studies, series, images, imageframes, metadata, and the images themselves
|
||||
must come from an external source. There are many, many ways to provide this
|
||||
information, the OHIF Viewer's scope **DOES NOT** encompass providing _any_
|
||||
data; only the configuration necessary to interface with one or more of these
|
||||
many data sources. The OHIF Viewer's scope **DOES** include configuration and
|
||||
support for services that are protected with OpenID-Connect.
|
||||
|
||||
In an effort to aide our users and contributors, we attempt to provide several
|
||||
[deployment and hosting recipes](./../deployment/index.md) as potential starting
|
||||
points. These are not meant to be rock solid, production ready, solutions; like
|
||||
most recipes, they should be augmented to best fit you and your organization's
|
||||
taste, preferences, etc.
|
||||
|
||||
## FAQ
|
||||
|
||||
_Am I able to cache studies for offline viewing?_
|
||||
|
||||
Not currently. A web page's offline cache capabilities are limited and somewhat
|
||||
volatile (mostly imposed at the browser vendor level). For more robust offline
|
||||
caching, you may want to consider a server on the local network, or packaging
|
||||
the OHIF Viewer as a desktop application.
|
||||
|
||||
_Does the OHIF Viewer work with the local filesystem?_
|
||||
|
||||
It is possible to accomplish this through extensions; however, for an user
|
||||
experience that accomodates a large number of studies, you would likely need to
|
||||
package the OHIF Viewer as an [Electron app][electron].
|
||||
|
||||
<!--
|
||||
Links
|
||||
-->
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
[simplicable]: https://simplicable.com/new/dumb-client
|
||||
[electron]: https://electronjs.org/
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,97 @@
|
||||
# Themeing
|
||||
|
||||
Themeing is currently accomplished with color variables that are defined within
|
||||
the [`:root`](https://css-tricks.com/almanac/selectors/r/root/) selector
|
||||
(allowing them to cascade across all elements). This repository's components,
|
||||
and the ones we consume from our
|
||||
[React Viewerbase component library](https://react.ohif.org/styling-and-theming)
|
||||
utilize them. We are interested in pursuing more robust themeing options, and
|
||||
open to pull requests and discussion issues.
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* Interface UI Colors */
|
||||
--default-color: #9ccef9;
|
||||
--hover-color: #ffffff;
|
||||
--active-color: #20a5d6;
|
||||
--ui-border-color: #44626f;
|
||||
--ui-border-color-dark: #3c5d80;
|
||||
--ui-border-color-active: #00a4d9;
|
||||
--primary-background-color: #000000;
|
||||
--box-background-color: #3e5975;
|
||||
|
||||
--text-primary-color: #ffffff;
|
||||
--text-secondary-color: #91b9cd;
|
||||
--input-background-color: #2c363f;
|
||||
--input-placeholder-color: #d3d3d3;
|
||||
|
||||
--table-hover-color: #2c363f;
|
||||
--table-text-primary-color: #ffffff;
|
||||
--table-text-secondary-color: #91b9cd;
|
||||
|
||||
--large-numbers-color: #6fbde2;
|
||||
|
||||
--state-error: #ffcccc;
|
||||
--state-error-border: #ffcccc;
|
||||
--state-error-text: #ffcccc;
|
||||
|
||||
/* Common palette */
|
||||
--ui-yellow: #e29e4a;
|
||||
--ui-sky-blue: #6fbde2;
|
||||
|
||||
/* State palette */
|
||||
--ui-state-error: #ffcccc;
|
||||
--ui-state-error-border: #993333;
|
||||
--ui-state-error-text: #661111;
|
||||
--ui-gray-lighter: #436270;
|
||||
--ui-gray-light: #516873;
|
||||
--ui-gray: #263340;
|
||||
--ui-gray-dark: #16202b;
|
||||
--ui-gray-darker: #151a1f;
|
||||
--ui-gray-darkest: #14202a;
|
||||
|
||||
--calendar-day-color: #d3d3d3;
|
||||
--calendar-day-border-color: #d3d3d3;
|
||||
--calendar-day-active-hover-background-color: #516873;
|
||||
--calendar-main-color: #263340;
|
||||
--viewport-border-thickness: 1px;
|
||||
}
|
||||
```
|
||||
|
||||
## White Labeling
|
||||
|
||||
> A white-label product is a product or service produced by one company (the
|
||||
> producer) that other companies (the marketers) rebrand to make it appear as if
|
||||
> they had made it - [Wikipedia: White-Label Product][wikipedia]
|
||||
|
||||
Current white-labeling options are limited. We expose the ability to replace the
|
||||
"Logo" section of the application with a custom "Logo" component. You can do
|
||||
this by adding a `whiteLabelling` key to your
|
||||
[configuration file](./configuration.md).
|
||||
|
||||
```js
|
||||
function RadicalImagingLogo() {
|
||||
return React.createElement(
|
||||
'a',
|
||||
{
|
||||
target: '_blank',
|
||||
rel: 'noopener noreferrer',
|
||||
className: 'header-brand',
|
||||
href: 'http://radicalimaging.com',
|
||||
},
|
||||
React.createElement('h5', {}, 'RADICAL IMAGING')
|
||||
)
|
||||
}
|
||||
|
||||
props.whiteLabelling = {
|
||||
logoComponent: RadicalImagingLogo(),
|
||||
}
|
||||
```
|
||||
|
||||
<!--
|
||||
Links
|
||||
-->
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
[wikipedia]: https://en.wikipedia.org/wiki/White-label_product
|
||||
<!-- prettier-ignore-end -->
|
||||
@@ -0,0 +1,317 @@
|
||||
# Translating
|
||||
|
||||
OHIF supports internationalization using [i18next](https://www.i18next.com/)
|
||||
through the npm package [@ohif/i18n](https://www.npmjs.com/package/@ohif/i18n),
|
||||
where is the main instance of i18n containing several languages and tools.
|
||||
|
||||
<div class='row'>
|
||||
<div class='column'>
|
||||
<p>Our translation management is powered by <a href="https://locize.com/" target="_blank" rel="noopener noreferrer">Locize</a> through their generous support of open source.</p>
|
||||
</div>
|
||||
<div class='column'>
|
||||
<a href="https://locize.com/" target="_blank" rel="noopener noreferrer" style='padding: 20px'>
|
||||
<img src="../assets/img/locizeSponsor.svg" alt="Locize Translation Management Logo">
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
### Installing
|
||||
|
||||
```bash
|
||||
yarn add @ohif/i18n
|
||||
|
||||
# OR
|
||||
|
||||
npm install --save @ohif/i18n
|
||||
```
|
||||
|
||||
### How it works
|
||||
|
||||
After installing `@ohif/i18n` npm package, the translation function
|
||||
[t](https://www.i18next.com/overview/api#t) can be used [with](#with-react) or
|
||||
[without](#without-react) React.
|
||||
|
||||
A translation will occur every time a text match happens in a
|
||||
[t](https://www.i18next.com/overview/api#t) function.
|
||||
|
||||
The [t](https://www.i18next.com/overview/api#t) function is responsible for
|
||||
getting translations using all the power of i18next.
|
||||
|
||||
E.g.
|
||||
|
||||
Before:
|
||||
|
||||
```html
|
||||
<div>my translated text</div>
|
||||
```
|
||||
|
||||
After:
|
||||
|
||||
```html
|
||||
<div>{t('my translated text')}</div>
|
||||
```
|
||||
|
||||
If the translation.json file contains a key that matches the HTML content e.g.
|
||||
`my translated text`, it will be replaced automatically by the
|
||||
[t](https://www.i18next.com/overview/api#t) function.
|
||||
|
||||
---
|
||||
|
||||
#### With React
|
||||
|
||||
This section will introduce you to [react-i18next](https://react.i18next.com/)
|
||||
basics and show how to implement the [t](https://www.i18next.com/overview/api#t)
|
||||
function easily.
|
||||
|
||||
##### Using HOCs
|
||||
|
||||
In most cases we used
|
||||
[High Order Components](https://react.i18next.com/latest/withtranslation-hoc) to
|
||||
share the `t` function among OHIF's components.
|
||||
|
||||
E.g.
|
||||
|
||||
```js
|
||||
import React from 'react';
|
||||
import { withTranslation } from '@ohif/i18n';
|
||||
|
||||
function MyComponent({ t, i18n }) {
|
||||
return <p>{t('my translated text')}</p>;
|
||||
}
|
||||
|
||||
export default withTranslation('MyNameSpace')(MyComponent);
|
||||
```
|
||||
|
||||
> Important: if you are using React outside the OHIF Viewer, check the
|
||||
> [I18nextProvider](#using-outside-of-ohif-viewer) section, `withTranslation`
|
||||
> HOC doesnt works without a I18nextProvider
|
||||
|
||||
##### Using Hooks
|
||||
|
||||
Also, it's possible to get the `t` tool using
|
||||
[React Hooks](https://react.i18next.com/latest/usetranslation-hook), but it
|
||||
requires at least React > 16.8 😉
|
||||
|
||||
#### Using outside of OHIF viewer
|
||||
|
||||
OHIF Viewer already sets a main
|
||||
[I18nextProvider](https://react.i18next.com/latest/i18nextprovider) connected to
|
||||
the shared i18n instance from `@ohif/i18n`, all extensions inside OHIF Viewer
|
||||
will share this same provider at the end, you don't need to set new providers at
|
||||
all.
|
||||
|
||||
But, if you need to use it completely outside of OHIF viewer, you can set the
|
||||
I18nextProvider this way:
|
||||
|
||||
```js
|
||||
import i18n from '@ohif/i18n';
|
||||
import { I18nextProvider } from 'react-i18next';
|
||||
import App from './App';
|
||||
|
||||
<I18nextProvider i18n={i18n}>
|
||||
<App />
|
||||
</I18nextProvider>;
|
||||
```
|
||||
|
||||
After setting `I18nextProvider` in your React App, all translations from
|
||||
`@ohif/i18n` should be available following the basic [With React](#with-react)
|
||||
usage.
|
||||
|
||||
---
|
||||
|
||||
#### Without React
|
||||
|
||||
When needed, you can also use available translations _without React_.
|
||||
|
||||
E.g.
|
||||
|
||||
```js
|
||||
import { T } from '@ohif/i18n';
|
||||
console.log(T('my translated text'));
|
||||
console.log(T('$t(Common:Play) my translated text'));
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Main Concepts While Translating
|
||||
|
||||
## - Namespaces
|
||||
|
||||
Namespaces are being used to organize translations in smaller portions, combined
|
||||
semantically or by use. Each `.json` file inside `@ohif/i18n` npm package
|
||||
becomes a new namespace automatically.
|
||||
|
||||
- Buttons: All buttons translations
|
||||
- CineDialog: Translations for the toll tips inside the Cine Player Dialog
|
||||
- Common: all common jargons that can be reused like `t('$t(common:image)')`
|
||||
- Header: translations related to OHIF's Header Top Bar
|
||||
- MeasurementTable - Translations for the react-viewerbase Measurement Table
|
||||
- UserPreferencesModal - Translations for the react-viewerbase Preferences Modal
|
||||
|
||||
### How to use another NameSpace inside the current NameSpace?
|
||||
|
||||
i18next provides a parsing feature able to get translations strings from any
|
||||
NameSpace, like this following example getting data from `Common` NameSpace:
|
||||
|
||||
```
|
||||
$t(Common:Reset)
|
||||
```
|
||||
|
||||
## - Extending Languages in @ohif/i18n
|
||||
|
||||
Sometimes, even using the same language, some nouns or jargons can change
|
||||
according to the country, states or even from Hospital to Hospital.
|
||||
|
||||
In this cases, you don't need to set an entire language again, you can extend
|
||||
languages creating a new folder inside a pre existent language folder and
|
||||
@ohif/i18n will do the hard work.
|
||||
|
||||
This new folder must to be called with a double character name, like the `UK` in
|
||||
the following file tree:
|
||||
|
||||
```bash
|
||||
|-- src
|
||||
|-- locales
|
||||
index.js
|
||||
|-- en
|
||||
|-- Buttons.json
|
||||
index.js
|
||||
| UK
|
||||
|-- Buttons.js
|
||||
indes.js
|
||||
| US
|
||||
|-- Buttons.js
|
||||
index.js
|
||||
...
|
||||
```
|
||||
|
||||
All properties inside a Namespace will be merged in the new sub language, e.g
|
||||
`en-US` and `en-UK` will merge the props with `en`, using i18next's fallback
|
||||
languages tool.
|
||||
|
||||
You will need to export all Json files in your `index.js` file, mounting an
|
||||
object like this:
|
||||
|
||||
```js
|
||||
{
|
||||
en: {
|
||||
NameSpace: {
|
||||
keyWord1: 'keyWord1Translation',
|
||||
keyWord2: 'keyWord2Translation',
|
||||
keyWord3: 'keyWord3Translation',
|
||||
}
|
||||
},
|
||||
'en-UK': {
|
||||
NameSpace: {
|
||||
keyWord1: 'keyWord1DifferentTranslation',
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Please check the `index.js` files inside locales folder for an example of this
|
||||
exporting structure.
|
||||
|
||||
### - Extending languages dynamically
|
||||
|
||||
You have access to the i18next instance, so you can use the
|
||||
[addResourceBundle](https://www.i18next.com/how-to/add-or-load-translations#add-after-init)
|
||||
method to add and change language resources as needed.
|
||||
|
||||
E.g.
|
||||
|
||||
```js
|
||||
import { i18n } from '@ohif/i18n';
|
||||
i18next.addResourceBundle('pt-BR', 'Buttons', {
|
||||
Angle: 'Ângulo',
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### How to set a whole new language
|
||||
|
||||
To set a brand new language you can do it in two different ways:
|
||||
|
||||
- Opening a pull request for `@ohif/i18n` and sharing the translation with the
|
||||
community. 😍 Please see [Contributing](#contributing-with-new-languages)
|
||||
section for further information.
|
||||
|
||||
- Setting it only in your project or extension:
|
||||
|
||||
You'll need a a final object like the following, what is setting French as
|
||||
language, and send it to `addLocales` method.
|
||||
|
||||
```js
|
||||
const newLanguage =
|
||||
{
|
||||
fr: {
|
||||
Commons: {
|
||||
"Reset": "Réinitialiser",
|
||||
"Previous": "Précédent",
|
||||
},
|
||||
Buttons: {
|
||||
"Rectangle": "Rectangle",
|
||||
"Circle": "Cercle",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To make it easier to translate, you can copy the .json files in the /locales
|
||||
folder and theirs index.js exporters, keeping same keys and NameSpaces.
|
||||
Importing the main index.js file, will provide you an Object as expected by the
|
||||
method `addlocales`;
|
||||
|
||||
E.g. of `addLocales` usage
|
||||
|
||||
```js
|
||||
import { addLocales } from '@ohif/i18n';
|
||||
import locales from './locales/index.js';
|
||||
addLocales(locales);
|
||||
```
|
||||
|
||||
You can also set them manually, one by one, using this
|
||||
[method](#extending-languages-dynamically).
|
||||
|
||||
---
|
||||
|
||||
## Language Detections
|
||||
|
||||
@ohif/i18n uses
|
||||
[i18next-browser-languageDetector](https://github.com/i18next/i18next-browser-languageDetector)
|
||||
to manage detections, also exports a method called initI18n that accepts a new
|
||||
detector config as parameter.
|
||||
|
||||
### Changing the language
|
||||
|
||||
OHIF Viewer accepts a query param called `lng` in the url to change the
|
||||
language.
|
||||
|
||||
E.g.
|
||||
|
||||
```
|
||||
https://docs.ohif.org/demo/?lng=es-MX
|
||||
```
|
||||
|
||||
### Language Persistence
|
||||
|
||||
The user's language preference is kept automatically by the detector and stored
|
||||
at a cookie called 'i18next', and in a localstorage key called 'i18nextLng'.
|
||||
These names can be changed with a new
|
||||
[Detector Config](https://github.com/i18next/i18next-browser-languageDetector).
|
||||
|
||||
## Debugging translations
|
||||
|
||||
There is an environment variable responsible for debugging the translations,
|
||||
called `REACT_APP_I18N_DEBUG`.
|
||||
|
||||
Run the project as following to get full debug information:
|
||||
|
||||
```bash
|
||||
REACT_APP_I18N_DEBUG=true yarn run dev
|
||||
```
|
||||
|
||||
### Contributing with new languages
|
||||
|
||||
Contributions of any kind are welcome! Please check the
|
||||
[instructions](https://docs.ohif.org/contributing.html).
|
||||
@@ -0,0 +1,20 @@
|
||||
# Troubleshooting
|
||||
|
||||
Common GitHub issues that are not easily remedied with cleaner code or
|
||||
documentation will be recorded here. Please feel free to make PRs to update this
|
||||
page.
|
||||
|
||||
## Common Problems
|
||||
|
||||
| Problem | Most Common Reasons |
|
||||
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| ** Can't retrieve Study List over DICOMWeb** | 1. QIDO root URL is incorrect<br> 2. DICOM Web is not enabled on PACS |
|
||||
| ** Can't retrieve images** | 1. WADO Root URL is incorrect<br> 2. DICOM Web is not enabled on PACS<br> 3. HTTP Basic Authentication username and password are incorrect or not provided. |
|
||||
|
||||
## Debugging Steps
|
||||
|
||||
### Can't retrieve Study List over DICOMWeb
|
||||
|
||||
1. Check that you can query your PACS using an alternative DICOM Web client
|
||||
(e.g. cURL, or a Web Browser). If you cannot, then your PACS is configured
|
||||
incorrectly. Refer to the documentation of the image archive.
|
||||
Reference in new issue
Block a user