0
# @ngx-translate/http-loader
1

2
@ngx-translate/http-loader is an HTTP loader implementation for the @ngx-translate/core internationalization library in Angular applications. It enables dynamic loading of translation files from server endpoints, making it essential for applications that need to fetch JSON translation files at runtime rather than bundling them.
3

4
## Package Information
5

6
- **Package Name**: @ngx-translate/http-loader
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ngx-translate/http-loader`
10
- **Peer Dependencies**: `@angular/core >=16`, `@angular/common >=16`
11

12
## Core Imports
13

14
```typescript
15
import { 
16
  TranslateHttpLoader, 
17
  provideTranslateHttpLoader,
18
  TranslateHttpLoaderConfig,
19
  TRANSLATE_HTTP_LOADER_CONFIG
20
} from "@ngx-translate/http-loader";
21
import { TranslateLoader } from "@ngx-translate/core";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const { 
28
  TranslateHttpLoader, 
29
  provideTranslateHttpLoader,
30
  TRANSLATE_HTTP_LOADER_CONFIG
31
} = require("@ngx-translate/http-loader");
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { provideHttpClient } from "@angular/common/http";
38
import { provideTranslateService, TranslateLoader } from "@ngx-translate/core";
39
import { provideTranslateHttpLoader } from "@ngx-translate/http-loader";
40

41
// Using standalone providers (Angular 16+)
42
export const appConfig: ApplicationConfig = {
43
  providers: [
44
    provideHttpClient(),
45
    provideTranslateService(),
46
    provideTranslateHttpLoader({
47
      prefix: "/assets/i18n/",
48
      suffix: ".json"
49
    })
50
  ]
51
};
52

53
// Or using the class directly with injection token (for module-based apps)
54
import { TranslateHttpLoader, TRANSLATE_HTTP_LOADER_CONFIG } from "@ngx-translate/http-loader";
55

56
@NgModule({
57
  imports: [
58
    TranslateModule.forRoot({
59
      loader: {
60
        provide: TranslateLoader,
61
        useClass: TranslateHttpLoader
62
      }
63
    })
64
  ],
65
  providers: [
66
    {
67
      provide: TRANSLATE_HTTP_LOADER_CONFIG,
68
      useValue: {
69
        prefix: "/assets/i18n/",
70
        suffix: ".json"
71
      }
72
    }
73
  ]
74
})
75
export class AppModule { }
76
```
77

78
## Architecture
79

80
The loader is built around several key components:
81

82
- **TranslateHttpLoader Class**: Core implementation of the TranslateLoader interface
83
- **Configuration System**: Flexible configuration via dependency injection token
84
- **HTTP Client Abstraction**: Support for both HttpClient and HttpBackend for different use cases
85
- **Provider Function**: Modern Angular provider pattern for dependency injection setup
86

87
## Capabilities
88

89
### HTTP Translation Loading
90

91
Core functionality for loading translation files via HTTP requests with configurable paths and caching options.
92

93
```typescript { .api }
94
class TranslateHttpLoader implements TranslateLoader {
95
  /**
96
   * Creates a new HTTP loader instance with configuration from dependency injection
97
   * Uses TRANSLATE_HTTP_LOADER_CONFIG token for configuration
98
   * Defaults: prefix="/assets/i18n/", suffix=".json", enforceLoading=false, useHttpBackend=false
99
   */
100
  constructor();
101
  
102
  /**
103
   * Gets the translations from the server
104
   * @param lang - Language code for the translation file
105
   * @returns Observable of the translation object
106
   */
107
  getTranslation(lang: string): Observable<TranslationObject>;
108
}
109
```
110

111
### Dependency Injection Configuration
112

113
Provider function for configuring the HTTP loader in Angular's dependency injection system with comprehensive configuration options.
114

115
```typescript { .api }
116
/**
117
 * Provider function for configuring the HTTP loader with Angular dependency injection
118
 * @param config - Optional configuration object (default: {})
119
 * @returns Array of Angular providers including configuration token and TranslateLoader provider
120
 */
121
function provideTranslateHttpLoader(
122
  config?: Partial<TranslateHttpLoaderConfig>
123
): Provider[];
124
```
125

126
**Note**: The `provideTranslateHttpLoader` function creates providers that configure both the `TRANSLATE_HTTP_LOADER_CONFIG` injection token and the `TranslateLoader` service. The `TranslateHttpLoader` constructor uses Angular's modern `inject()` function internally for dependency injection rather than constructor parameters.
127

128
### Configuration Interface
129

130
Configuration interface defining all available options for customizing the HTTP loader behavior.
131

132
```typescript { .api }
133
interface TranslateHttpLoaderConfig {
134
  /** URL prefix for translation files (default: "/assets/i18n/") */
135
  prefix: string;
136
  /** File suffix for translation files (default: ".json") */
137
  suffix: string;
138
  /** Whether to add cache-busting parameters (default: false) */
139
  enforceLoading: boolean;
140
  /** Whether to use HttpBackend instead of HttpClient (default: false) */
141
  useHttpBackend: boolean;
142
}
143
```
144

145
### Injection Token
146

147
Angular injection token for providing HTTP loader configuration through dependency injection.
148

149
```typescript { .api }
150
const TRANSLATE_HTTP_LOADER_CONFIG: InjectionToken<Partial<TranslateHttpLoaderConfig>>;
151
```
152

153
## Types
154

155
```typescript { .api }
156
interface TranslateHttpLoaderConfig {
157
  prefix: string;
158
  suffix: string;
159
  enforceLoading: boolean;
160
  useHttpBackend: boolean;
161
}
162

163
// From @angular/core
164
type Provider = any;
165
type InjectionToken<T> = any;
166

167
// From rxjs
168
type Observable<T> = any;
169

170
// From @ngx-translate/core
171
interface TranslationObject {
172
  [key: string]: string | TranslationObject;
173
}
174
```
175

176
## Configuration Examples
177

178
**Basic Configuration:**
179
```typescript
180
provideTranslateHttpLoader()
181
// Uses defaults: prefix="/assets/i18n/", suffix=".json"
182
```
183

184
**Custom Paths:**
185
```typescript
186
provideTranslateHttpLoader({
187
  prefix: "/locales/",
188
  suffix: ".json"
189
})
190
// Loads from: /locales/{lang}.json
191
```
192

193
**Cache Busting:**
194
```typescript
195
provideTranslateHttpLoader({
196
  enforceLoading: true
197
})
198
// Adds timestamp: /assets/i18n/{lang}.json?enforceLoading=1234567890
199
```
200

201
**HttpBackend Usage:**
202
```typescript
203
provideTranslateHttpLoader({
204
  useHttpBackend: true
205
})
206
// Bypasses HTTP interceptors
207
```
208

209
## Error Handling
210

211
The loader inherits error handling from Angular's HttpClient. Common errors include:
212

213
- **Network errors**: Connection failures, timeouts
214
- **HTTP errors**: 404 (file not found), 403 (forbidden), 500 (server error)
215
- **Parse errors**: Invalid JSON format in translation files
216

217
All errors are propagated as Observable errors that can be handled by the @ngx-translate/core service.