paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

feat: api-docs pulgin support i18n

Browse Source 
Signed-off-by: mario ma <mario.ma.node@gmail.com>
This commit is contained in:
mario ma
2024-10-10 12:18:28 +08:00
parent 9ede6ffcb7
commit 317bc3dd1e
11 changed files with 195 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/calm-pans-leave.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-api-docs': patch
---
api-docs plugin support i18n
plugins/api-docs/src/components/ApiDefinitionDialog/ApiDefinitionDialog.tsx
+5 -2
View File
@@ -29,6 +29,8 @@ import { makeStyles } from '@material-ui/core/styles';
import { ReactNode, useState, useEffect } from 'react';
import { apiDocsConfigRef } from '../../config';
import { PlainApiDefinitionWidget } from '../PlainApiDefinitionWidget';
import { useTranslationRef } from '@backstage/frontend-plugin-api';
import { apiDocsTranslationRef } from '../../translation';
const useStyles = makeStyles(theme => ({
fullHeightDialog: {
@@ -108,6 +110,7 @@ export function ApiDefinitionDialog(props: {
const { open, entity, onClose } = props;
const [activeTab, setActiveTab] = useState(0);
const classes = useStyles();
const { t } = useTranslationRef(apiDocsTranslationRef);
useEffect(() => {
setActiveTab(0);
@@ -142,7 +145,7 @@ export function ApiDefinitionDialog(props: {
variant="scrollable"
value={activeTab}
onChange={(_, newValue) => setActiveTab(newValue)}
aria-label="API definition options"
aria-label={t('apiDefinitionDialog.tabsAriaLabel')}
className={classes.tabs}
>
{definitionWidget ? (
@@ -165,7 +168,7 @@ export function ApiDefinitionDialog(props: {
</DialogContent>
<DialogActions>
<Button onClick={onClose} color="primary">
Close
{t('apiDefinitionDialog.closeButtonTitle')}
</Button>
</DialogActions>
</Dialog>
plugins/api-docs/src/components/ApiExplorerPage/DefaultApiExplorerPage.tsx
+12 -7
View File
@@ -41,6 +41,8 @@ import {
import { registerComponentRouteRef } from '../../routes';
import { usePermission } from '@backstage/plugin-permission-react';
import { catalogEntityCreatePermission } from '@backstage/plugin-catalog-common/alpha';
import { useTranslationRef } from '@backstage/frontend-plugin-api';
import { apiDocsTranslationRef } from '../../translation';
const defaultColumns: TableColumn<CatalogTableRow>[] = [
CatalogTable.columns.createTitleColumn({ hidden: true }),
@@ -79,9 +81,10 @@ export const DefaultApiExplorerPage = (props: DefaultApiExplorerPageProps) => {
} = props;
const configApi = useApi(configApiRef);
const generatedSubtitle = `${
configApi.getOptionalString('organization.name') ?? 'Backstage'
} API Explorer`;
const { t } = useTranslationRef(apiDocsTranslationRef);
const generatedSubtitle = t('defaultApiExplorerPage.subtitle', {
orgName: configApi.getOptionalString('organization.name') ?? 'Backstage',
});
const registerComponentLink = useRouteRef(registerComponentRouteRef);
const { allowed } = usePermission({
permission: catalogEntityCreatePermission,
@@ -90,19 +93,21 @@ export const DefaultApiExplorerPage = (props: DefaultApiExplorerPageProps) => {
return (
<PageWithHeader
themeId="apis"
title="APIs"
title={t('defaultApiExplorerPage.title')}
subtitle={generatedSubtitle}
pageTitleOverride="APIs"
pageTitleOverride={t('defaultApiExplorerPage.pageTitleOverride')}
>
<Content>
<ContentHeader title="">
{allowed && (
<CreateButton
title="Register Existing API"
title={t('defaultApiExplorerPage.createButtonTitle')}
to={registerComponentLink?.()}
/>
)}
<SupportButton>All your APIs</SupportButton>
<SupportButton>
{t('defaultApiExplorerPage.supportButtonTitle')}
</SupportButton>
</ContentHeader>
<EntityListProvider pagination={pagination}>
<CatalogFilterLayout>
plugins/api-docs/src/components/ApisCards/ConsumedApisCard.tsx
+11 -7
View File
@@ -21,7 +21,7 @@ import {
useEntity,
useRelatedEntities,
} from '@backstage/plugin-catalog-react';
import { apiEntityColumns } from './presets';
import { getApiEntityColumns } from './presets';
import {
CodeSnippet,
InfoCard,
@@ -32,6 +32,8 @@ import {
TableOptions,
WarningPanel,
} from '@backstage/core-components';
import { useTranslationRef } from '@backstage/frontend-plugin-api';
import { apiDocsTranslationRef } from '../../translation';
/**
* @public
@@ -42,10 +44,11 @@ export const ConsumedApisCard = (props: {
columns?: TableColumn<ApiEntity>[];
tableOptions?: TableOptions;
}) => {
const { t } = useTranslationRef(apiDocsTranslationRef);
const {
variant = 'gridItem',
title = 'Consumed APIs',
columns = apiEntityColumns,
title = t('consumedApisCard.title'),
columns = getApiEntityColumns(t),
tableOptions = {},
} = props;
const { entity } = useEntity();
@@ -66,7 +69,7 @@ export const ConsumedApisCard = (props: {
<InfoCard variant={variant} title={title}>
<WarningPanel
severity="error"
title="Could not load APIs"
title={t('consumedApisCard.error.title')}
message={<CodeSnippet text={`${error}`} language="text" />}
/>
</InfoCard>
@@ -80,15 +83,16 @@ export const ConsumedApisCard = (props: {
emptyContent={
<div style={{ textAlign: 'center' }}>
<Typography variant="body1">
This {entity.kind.toLocaleLowerCase('en-US')} does not consume any
APIs.
{t('consumedApisCard.emptyContent.title', {
entity: entity.kind.toLocaleLowerCase('en-US'),
})}
</Typography>
<Typography variant="body2">
<Link
to="https://backstage.io/docs/features/software-catalog/descriptor-format#specconsumesapis-optional"
externalLinkIcon
>
Learn how to change this
{t('apisCardHelpLinkTitle')}
</Link>
</Typography>
</div>
plugins/api-docs/src/components/ApisCards/HasApisCard.tsx
+19 -13
View File
@@ -21,6 +21,7 @@ import {
useEntity,
useRelatedEntities,
} from '@backstage/plugin-catalog-react';
import { useMemo } from 'react';
import { createSpecApiTypeColumn } from './presets';
import {
CodeSnippet,
@@ -32,14 +33,8 @@ import {
TableOptions,
WarningPanel,
} from '@backstage/core-components';
const presetColumns: TableColumn<ApiEntity>[] = [
EntityTable.columns.createEntityRefColumn({ defaultKind: 'API' }),
EntityTable.columns.createOwnerColumn(),
createSpecApiTypeColumn(),
EntityTable.columns.createSpecLifecycleColumn(),
EntityTable.columns.createMetadataDescriptionColumn(),
];
import { useTranslationRef } from '@backstage/frontend-plugin-api';
import { apiDocsTranslationRef } from '../../translation';
/**
* @public
@@ -50,9 +45,19 @@ export const HasApisCard = (props: {
columns?: TableColumn<ApiEntity>[];
tableOptions?: TableOptions;
}) => {
const { t } = useTranslationRef(apiDocsTranslationRef);
const presetColumns: TableColumn<ApiEntity>[] = useMemo(() => {
return [
EntityTable.columns.createEntityRefColumn({ defaultKind: 'API' }),
EntityTable.columns.createOwnerColumn(),
createSpecApiTypeColumn(t),
EntityTable.columns.createSpecLifecycleColumn(),
EntityTable.columns.createMetadataDescriptionColumn(),
];
}, [t]);
const {
variant = 'gridItem',
title = 'APIs',
title = t('hasApisCard.title'),
columns = presetColumns,
tableOptions = {},
} = props;
@@ -75,7 +80,7 @@ export const HasApisCard = (props: {
<InfoCard variant={variant} title={title}>
<WarningPanel
severity="error"
title="Could not load APIs"
title={t('hasApisCard.error.title')}
message={<CodeSnippet text={`${error}`} language="text" />}
/>
</InfoCard>
@@ -89,12 +94,13 @@ export const HasApisCard = (props: {
emptyContent={
<div style={{ textAlign: 'center' }}>
<Typography variant="body1">
This {entity.kind.toLocaleLowerCase('en-US')} does not contain any
APIs.
{t('hasApisCard.emptyContent.title', {
entity: entity.kind.toLocaleLowerCase('en-US'),
})}
</Typography>
<Typography variant="body2">
<Link to="https://backstage.io/docs/features/software-catalog/descriptor-format#kind-api">
Learn how to change this.
{t('apisCardHelpLinkTitle')}
</Link>
</Typography>
</div>
plugins/api-docs/src/components/ApisCards/ProvidedApisCard.tsx
+11 -7
View File
@@ -21,7 +21,7 @@ import {
useEntity,
useRelatedEntities,
} from '@backstage/plugin-catalog-react';
import { apiEntityColumns } from './presets';
import { getApiEntityColumns } from './presets';
import {
CodeSnippet,
InfoCard,
@@ -32,6 +32,8 @@ import {
TableOptions,
WarningPanel,
} from '@backstage/core-components';
import { useTranslationRef } from '@backstage/frontend-plugin-api';
import { apiDocsTranslationRef } from '../../translation';
/**
* @public
@@ -42,10 +44,11 @@ export const ProvidedApisCard = (props: {
columns?: TableColumn<ApiEntity>[];
tableOptions?: TableOptions;
}) => {
const { t } = useTranslationRef(apiDocsTranslationRef);
const {
variant = 'gridItem',
title = 'Provided APIs',
columns = apiEntityColumns,
title = t('providedApisCard.title'),
columns = getApiEntityColumns(t),
tableOptions = {},
} = props;
const { entity } = useEntity();
@@ -66,7 +69,7 @@ export const ProvidedApisCard = (props: {
<InfoCard variant={variant} title={title}>
<WarningPanel
severity="error"
title="Could not load APIs"
title={t('providedApisCard.error.title')}
message={<CodeSnippet text={`${error}`} language="text" />}
/>
</InfoCard>
@@ -80,15 +83,16 @@ export const ProvidedApisCard = (props: {
emptyContent={
<div style={{ textAlign: 'center' }}>
<Typography variant="body1">
This {entity.kind.toLocaleLowerCase('en-US')} does not provide any
APIs.
{t('providedApisCard.emptyContent.title', {
entity: entity.kind.toLocaleLowerCase('en-US'),
})}
</Typography>
<Typography variant="body2">
<Link
to="https://backstage.io/docs/features/software-catalog/descriptor-format#specprovidesapis-optional"
externalLinkIcon
>
Learn how to change this
{t('apisCardHelpLinkTitle')}
</Link>
</Typography>
</div>
plugins/api-docs/src/components/ApisCards/presets.tsx
+28 -14
View File
@@ -22,10 +22,17 @@ import ToggleButton from '@material-ui/lab/ToggleButton';
import { useState } from 'react';
import { ApiTypeTitle } from '../ApiDefinitionCard';
import { ApiDefinitionDialog } from '../ApiDefinitionDialog';
import {
TranslationFunction,
useTranslationRef,
} from '@backstage/core-plugin-api/alpha';
import { apiDocsTranslationRef } from '../../translation';
export function createSpecApiTypeColumn(): TableColumn<ApiEntity> {
export function createSpecApiTypeColumn(
t: TranslationFunction<typeof apiDocsTranslationRef.T>,
): TableColumn<ApiEntity> {
return {
title: 'Type',
title: t('apiEntityColumns.typeTitle'),
field: 'spec.type',
render: entity => <ApiTypeTitle apiEntity={entity} />,
};
@@ -33,10 +40,11 @@ export function createSpecApiTypeColumn(): TableColumn<ApiEntity> {
const ApiDefinitionButton = ({ apiEntity }: { apiEntity: ApiEntity }) => {
const [dialogOpen, setDialogOpen] = useState(false);
const { t } = useTranslationRef(apiDocsTranslationRef);
return (
<>
<ToggleButton
aria-label="Toggle API Definition Dialog"
aria-label={t('apiDefinitionDialog.toggleButtonAriaLabel')}
onClick={() => setDialogOpen(!dialogOpen)}
value={dialogOpen}
>
@@ -51,19 +59,25 @@ const ApiDefinitionButton = ({ apiEntity }: { apiEntity: ApiEntity }) => {
);
};
function createApiDefinitionColumn(): TableColumn<ApiEntity> {
function createApiDefinitionColumn(
t: TranslationFunction<typeof apiDocsTranslationRef.T>,
): TableColumn<ApiEntity> {
return {
title: 'API Definition',
title: t('apiEntityColumns.apiDefinitionTitle'),
render: entity => <ApiDefinitionButton apiEntity={entity} />,
};
}
export const apiEntityColumns: TableColumn<ApiEntity>[] = [
EntityTable.columns.createEntityRefColumn({ defaultKind: 'API' }),
EntityTable.columns.createSystemColumn(),
EntityTable.columns.createOwnerColumn(),
createSpecApiTypeColumn(),
EntityTable.columns.createSpecLifecycleColumn(),
EntityTable.columns.createMetadataDescriptionColumn(),
createApiDefinitionColumn(),
];
export const getApiEntityColumns = (
t: TranslationFunction<typeof apiDocsTranslationRef.T>,
): TableColumn<ApiEntity>[] => {
return [
EntityTable.columns.createEntityRefColumn({ defaultKind: 'API' }),
EntityTable.columns.createSystemColumn(),
EntityTable.columns.createOwnerColumn(),
createSpecApiTypeColumn(t),
EntityTable.columns.createSpecLifecycleColumn(),
EntityTable.columns.createMetadataDescriptionColumn(),
createApiDefinitionColumn(t),
];
};
plugins/api-docs/src/components/ComponentsCards/ConsumingComponentsCard.tsx
+9 -6
View File
@@ -33,6 +33,8 @@ import {
TableColumn,
WarningPanel,
} from '@backstage/core-components';
import { useTranslationRef } from '@backstage/frontend-plugin-api';
import { apiDocsTranslationRef } from '../../translation';
/**
* @public
@@ -47,10 +49,11 @@ export const ConsumingComponentsCard = (props: {
const { entities, loading, error } = useRelatedEntities(entity, {
type: RELATION_API_CONSUMED_BY,
});
const { t } = useTranslationRef(apiDocsTranslationRef);
if (loading) {
return (
<InfoCard variant={variant} title="Consumers">
<InfoCard variant={variant} title={t('consumingComponentsCard.title')}>
<Progress />
</InfoCard>
);
@@ -58,10 +61,10 @@ export const ConsumingComponentsCard = (props: {
if (error || !entities) {
return (
<InfoCard variant={variant} title="Consumers">
<InfoCard variant={variant} title={t('consumingComponentsCard.title')}>
<WarningPanel
severity="error"
title="Could not load components"
title={t('consumingComponentsCard.error.title')}
message={<CodeSnippet text={`${error}`} language="text" />}
/>
</InfoCard>
@@ -70,16 +73,16 @@ export const ConsumingComponentsCard = (props: {
return (
<EntityTable
title="Consumers"
title={t('consumingComponentsCard.title')}
variant={variant}
emptyContent={
<div style={{ textAlign: 'center' }}>
<Typography variant="body1">
No component consumes this API.
{t('consumingComponentsCard.emptyContent.title')}
</Typography>
<Typography variant="body2">
<Link to="https://backstage.io/docs/features/software-catalog/descriptor-format#specconsumesapis-optional">
Learn how to change this.
{t('apisCardHelpLinkTitle')}
</Link>
</Typography>
</div>
plugins/api-docs/src/components/ComponentsCards/ProvidingComponentsCard.tsx
+9 -6
View File
@@ -33,6 +33,8 @@ import {
TableColumn,
WarningPanel,
} from '@backstage/core-components';
import { useTranslationRef } from '@backstage/frontend-plugin-api';
import { apiDocsTranslationRef } from '../../translation';
/** @public */
export const ProvidingComponentsCard = (props: {
@@ -45,10 +47,11 @@ export const ProvidingComponentsCard = (props: {
const { entities, loading, error } = useRelatedEntities(entity, {
type: RELATION_API_PROVIDED_BY,
});
const { t } = useTranslationRef(apiDocsTranslationRef);
if (loading) {
return (
<InfoCard variant={variant} title="Providers">
<InfoCard variant={variant} title={t('providingComponentsCard.title')}>
<Progress />
</InfoCard>
);
@@ -56,10 +59,10 @@ export const ProvidingComponentsCard = (props: {
if (error || !entities) {
return (
<InfoCard variant={variant} title="Providers">
<InfoCard variant={variant} title={t('providingComponentsCard.title')}>
<WarningPanel
severity="error"
title="Could not load components"
title={t('providingComponentsCard.error.title')}
message={<CodeSnippet text={`${error}`} language="text" />}
/>
</InfoCard>
@@ -68,16 +71,16 @@ export const ProvidingComponentsCard = (props: {
return (
<EntityTable
title="Providers"
title={t('providingComponentsCard.title')}
variant={variant}
emptyContent={
<div style={{ textAlign: 'center' }}>
<Typography variant="body1">
No component provides this API.
{t('providingComponentsCard.emptyContent.title')}
</Typography>
<Typography variant="body2">
<Link to="https://backstage.io/docs/features/software-catalog/descriptor-format#specprovidesapis-optional">
Learn how to change this.
{t('apisCardHelpLinkTitle')}
</Link>
</Typography>
</div>
plugins/api-docs/src/translation.ts
+85
View File
@@ -0,0 +1,85 @@
/*
* Copyright 2025 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { createTranslationRef } from '@backstage/frontend-plugin-api';
export const apiDocsTranslationRef = createTranslationRef({
id: 'api-docs',
messages: {
apiDefinitionDialog: {
closeButtonTitle: 'Close',
tabsAriaLabel: 'API definition options',
toggleButtonAriaLabel: 'Toggle API Definition Dialog',
},
defaultApiExplorerPage: {
title: 'APIs',
subtitle: '{{orgName}} API Explorer',
pageTitleOverride: 'APIs',
createButtonTitle: 'Register Existing API',
supportButtonTitle: 'All your APIs',
},
consumedApisCard: {
title: 'Consumed APIs',
error: {
title: 'Could not load APIs',
},
emptyContent: {
title: 'This {{entity}} does not consume any APIs.',
},
},
hasApisCard: {
title: 'APIs',
error: {
title: 'Could not load APIs',
},
emptyContent: {
title: 'This {{entity}} does not contain any APIs.',
},
},
providedApisCard: {
title: 'Provided APIs',
error: {
title: 'Could not load APIs',
},
emptyContent: {
title: 'This {{entity}} does not provide any APIs.',
},
},
apiEntityColumns: {
typeTitle: 'Type',
apiDefinitionTitle: 'API Definition',
},
consumingComponentsCard: {
title: 'Consumers',
error: {
title: 'Could not load components',
},
emptyContent: {
title: 'No component consumes this API.',
},
},
providingComponentsCard: {
title: 'Providers',
error: {
title: 'Could not load components',
},
emptyContent: {
title: 'No component provides this API.',
},
},
apisCardHelpLinkTitle: 'Learn how to change this',
},
});
plugins/scaffolder/report-alpha.api.md
+1 -1
View File
@@ -413,8 +413,8 @@ export const scaffolderTranslationRef: TranslationRef<
readonly 'templateListPage.pageTitle': 'Create a new component';
readonly 'templateListPage.templateGroups.defaultTitle': 'Templates';
readonly 'templateListPage.templateGroups.otherTitle': 'Other Templates';
readonly 'templateListPage.contentHeader.registerExistingButtonTitle': 'Register Existing Component';
readonly 'templateListPage.contentHeader.supportButtonTitle': 'Create new software components using standard templates. Different templates create different kinds of components (services, websites, documentation, ...).';
readonly 'templateListPage.contentHeader.registerExistingButtonTitle': 'Register Existing Component';
readonly 'templateListPage.additionalLinksForEntity.viewTechDocsTitle': 'View TechDocs';
readonly 'templateWizardPage.title': 'Create a new component';
readonly 'templateWizardPage.subtitle': 'Create new software components using standard templates in your organization';